{"components":{"parameters":{"ResourceId":{"description":"The resource identifier.","in":"path","name":"id","required":true,"schema":{"type":"string"}}},"responses":{"BadRequest":{"content":{"application/json":{"examples":{"invalidParameter":{"value":{"message":"limit must be an integer between 1 and 100.","name":"bad_request"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The request parameters are invalid."},"Conflict":{"content":{"application/json":{"examples":{"resourceNotReady":{"value":{"message":"The knowledge document does not have indexed content yet.","name":"conflict"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The operation conflicts with the resource's current state."},"InternalServerError":{"content":{"application/json":{"examples":{"unexpectedFailure":{"value":{"message":"Internal server error.","name":"internal_server_error"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The request failed unexpectedly."},"NotFound":{"content":{"application/json":{"examples":{"missingResource":{"value":{"message":"The requested resource was not found.","name":"not_found"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The resource does not exist for the authenticated agent."},"PayloadTooLarge":{"content":{"application/json":{"examples":{"fileTooLarge":{"value":{"message":"Files must be 10 MB or smaller.","name":"payload_too_large"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The uploaded file exceeds the maximum allowed size."},"RateLimited":{"content":{"application/json":{"examples":{"tooManyRequests":{"value":{"message":"Too many requests. Please try again later.","name":"rate_limited"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too many requests. Retry after the number of seconds in Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"ServiceUnavailable":{"content":{"application/json":{"examples":{"temporarilyUnavailable":{"value":{"message":"The API is temporarily unavailable.","name":"service_unavailable"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API is temporarily unavailable. The request was not processed.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"Unauthorized":{"content":{"application/json":{"examples":{"invalidKey":{"value":{"message":"The supplied API key is invalid or revoked.","name":"unauthorized"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The Agent API key is missing, invalid, or revoked.","headers":{"WWW-Authenticate":{"description":"The HTTP Bearer authentication challenge.","example":"Bearer realm=\"HeroUI Agents API\"","schema":{"type":"string"}}}},"UnsupportedMediaType":{"content":{"application/json":{"examples":{"unsupportedFile":{"value":{"message":"The uploaded file type is not supported.","name":"unsupported_media_type"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The request or uploaded file uses an unsupported media type."}},"schemas":{"Conversation":{"additionalProperties":false,"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"object":{"const":"conversation","type":"string"},"source":{"enum":["embed","preview",null],"type":["string","null"]},"status":{"enum":["aborted","completed","failed","streaming",null],"type":["string","null"]},"title":{"type":["string","null"]},"updated_at":{"format":"date-time","type":"string"},"user_id":{"type":["string","null"]}},"required":["object","id","title","status","source","user_id","created_at","updated_at"],"type":"object"},"ConversationList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Conversation"},"type":"array"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"object":{"const":"list","type":"string"}},"required":["object","data","has_more","next_cursor"],"type":"object"},"Error":{"additionalProperties":false,"properties":{"message":{"type":"string"},"name":{"enum":["bad_request","conflict","insufficient_scope","internal_server_error","not_found","payload_too_large","rate_limited","service_unavailable","unauthorized","unsupported_media_type"],"type":"string"}},"required":["name","message"],"type":"object"},"KnowledgeDocument":{"additionalProperties":false,"properties":{"character_count":{"minimum":0,"type":["integer","null"]},"created_at":{"format":"date-time","type":"string"},"error_message":{"type":["string","null"]},"file_name":{"type":["string","null"]},"file_size_bytes":{"minimum":0,"type":["integer","null"]},"id":{"type":"string"},"is_enabled":{"type":"boolean"},"last_checked_at":{"format":"date-time","type":["string","null"]},"last_synced_at":{"format":"date-time","type":["string","null"]},"name":{"maxLength":120,"minLength":1,"type":"string"},"next_refresh_at":{"format":"date-time","type":["string","null"]},"object":{"const":"knowledge_document","type":"string"},"refresh_error_message":{"type":["string","null"]},"refresh_interval_hours":{"enum":[0,6,12,24,168,null],"type":["integer","null"]},"refresh_status":{"enum":["idle","refreshing","failed"],"type":"string"},"source_type":{"enum":["file","url"],"type":"string"},"source_url":{"format":"uri","type":["string","null"]},"status":{"enum":["processing","ready","failed"],"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["object","id","name","source_type","source_url","file_name","file_size_bytes","is_enabled","status","error_message","refresh_status","refresh_error_message","refresh_interval_hours","character_count","last_checked_at","last_synced_at","next_refresh_at","created_at","updated_at"],"type":"object"},"KnowledgeDocumentList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/KnowledgeDocument"},"type":"array"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"object":{"const":"list","type":"string"}},"required":["object","data","has_more","next_cursor"],"type":"object"},"KnowledgeDocumentScheduleUpdate":{"additionalProperties":false,"properties":{"refresh_interval_hours":{"enum":[0,6,12,24,168],"type":"integer"}},"required":["refresh_interval_hours"],"type":"object"},"KnowledgeDocumentUpdate":{"additionalProperties":false,"anyOf":[{"required":["name"]},{"required":["is_enabled"]}],"properties":{"is_enabled":{"type":"boolean"},"name":{"maxLength":120,"minLength":1,"type":"string"}},"type":"object"},"KnowledgeUrlCreate":{"additionalProperties":false,"properties":{"name":{"maxLength":120,"minLength":1,"type":"string"},"refresh_interval_hours":{"default":24,"enum":[0,6,12,24,168],"type":"integer"},"url":{"description":"An HTTP or HTTPS URL. A bare hostname is normalized to an HTTPS URL.","minLength":1,"type":"string"}},"required":["url"],"type":"object"},"Message":{"additionalProperties":false,"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"object":{"const":"message","type":"string"},"parts":{"description":"AI SDK message parts as they were persisted for this conversation.","items":{},"type":"array"},"role":{"enum":["assistant","system","user"],"type":"string"},"source_id":{"type":["string","null"]},"updated_at":{"format":"date-time","type":["string","null"]}},"required":["object","id","role","parts","source_id","created_at","updated_at"],"type":"object"},"MessageList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Message"},"type":"array"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"object":{"const":"list","type":"string"}},"required":["object","data","has_more","next_cursor"],"type":"object"},"Run":{"additionalProperties":false,"properties":{"cache_read_tokens":{"minimum":0,"type":["integer","null"]},"cache_write_tokens":{"minimum":0,"type":["integer","null"]},"completed_at":{"format":"date-time","type":["string","null"]},"component_kinds":{"items":{"type":"string"},"type":"array"},"conversation_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"credits_charged":{"minimum":0,"type":["number","null"]},"effort":{"type":["string","null"]},"error_code":{"type":["string","null"]},"failed_tool_names":{"items":{"type":"string"},"type":"array"},"first_chunk_at":{"format":"date-time","type":["string","null"]},"id":{"type":"string"},"input_tokens":{"minimum":0,"type":["integer","null"]},"model_id":{"type":["string","null"]},"object":{"const":"run","type":"string"},"output_tokens":{"minimum":0,"type":["integer","null"]},"protocol_version":{"minimum":1,"type":"integer"},"request_id":{"type":"string"},"sdk_version":{"type":"string"},"status":{"enum":["aborted","completed","failed","streaming"],"type":"string"},"tool_names":{"items":{"type":"string"},"type":"array"},"total_tokens":{"minimum":0,"type":["integer","null"]},"total_turn_latency_ms":{"minimum":0,"type":["number","null"]},"updated_at":{"format":"date-time","type":"string"},"user_id":{"type":["string","null"]}},"required":["object","id","conversation_id","user_id","request_id","status","model_id","effort","sdk_version","protocol_version","input_tokens","output_tokens","total_tokens","cache_read_tokens","cache_write_tokens","credits_charged","tool_names","failed_tool_names","component_kinds","error_code","first_chunk_at","completed_at","total_turn_latency_ms","created_at","updated_at"],"type":"object"},"RunList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Run"},"type":"array"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"object":{"const":"list","type":"string"}},"required":["object","data","has_more","next_cursor"],"type":"object"},"User":{"additionalProperties":false,"properties":{"avatar_url":{"format":"uri","type":["string","null"]},"display_name":{"type":["string","null"]},"email":{"format":"email","type":["string","null"]},"external_id":{"type":["string","null"]},"first_seen_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"identity_type":{"description":"The observed identity kind. Current integrations use anonymous, user, or preview; legacy rows can report unknown.","type":"string"},"last_seen_at":{"format":"date-time","type":"string"},"object":{"const":"user","type":"string"}},"required":["object","id","external_id","identity_type","display_name","email","avatar_url","first_seen_at","last_seen_at"],"type":"object"},"UserList":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/User"},"type":"array"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"object":{"const":"list","type":"string"}},"required":["object","data","has_more","next_cursor"],"type":"object"}},"securitySchemes":{"AgentApiKey":{"bearerFormat":"he_...","description":"An Agent API key with the permission required by the operation.","scheme":"bearer","type":"http"}}},"info":{"description":"View Agent activity and manage the Agent's knowledge documents. Every request is scoped to the Agent that owns the supplied API key.","title":"HeroUI Agents API","version":"1.1.0"},"openapi":"3.1.0","paths":{"/conversations":{"get":{"description":"Returns conversations for the authenticated agent, ordered from most recently updated to oldest. Message content is available from List conversation messages.","operationId":"listConversations","parameters":[{"description":"The maximum number of objects to return. Defaults to 20 and is capped at 100.","in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"description":"An opaque cursor returned by the previous page.","in":"query","name":"after","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationList"}}},"description":"A page of conversations."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required conversations:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"conversations:read\"","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"List conversations","tags":["Conversations"],"x-required-scope":"conversations:read"}},"/conversations/{id}":{"get":{"description":"Returns one conversation that belongs to the authenticated agent.","operationId":"retrieveConversation","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}},"description":"The conversation."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required conversations:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"conversations:read\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Retrieve a conversation","tags":["Conversations"],"x-required-scope":"conversations:read"}},"/conversations/{id}/messages":{"get":{"description":"Returns persisted messages for one conversation, ordered from oldest to newest. The conversation must belong to the authenticated agent.","operationId":"listConversationMessages","parameters":[{"$ref":"#/components/parameters/ResourceId"},{"description":"The maximum number of objects to return. Defaults to 20 and is capped at 100.","in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"description":"An opaque cursor returned by the previous page.","in":"query","name":"after","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"}}},"description":"A page of conversation messages."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required conversations:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"conversations:read\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"List conversation messages","tags":["Conversations"],"x-required-scope":"conversations:read"}},"/knowledge":{"get":{"description":"Returns knowledge documents for the authenticated Agent, ordered from newest to oldest. Poll this endpoint or Retrieve a knowledge document to observe processing status.","operationId":"listKnowledgeDocuments","parameters":[{"description":"The maximum number of objects to return. Defaults to 20 and is capped at 100.","in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"description":"An opaque cursor returned by the previous page.","in":"query","name":"after","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocumentList"}}},"description":"A page of knowledge documents."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required knowledge:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"knowledge:read\"","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"List knowledge documents","tags":["Knowledge"],"x-required-scope":"knowledge:read"}},"/knowledge/files":{"post":{"description":"Uploads one file up to 10 MB and starts extraction and indexing. Supported formats are PDF, Word, Excel, PowerPoint, text, Markdown, HTML, CSV, and JSON. The returned document begins in processing status.","operationId":"uploadKnowledgeFile","requestBody":{"content":{"multipart/form-data":{"schema":{"additionalProperties":false,"properties":{"file":{"format":"binary","type":"string"},"name":{"maxLength":120,"minLength":1,"type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocument"}}},"description":"The knowledge document was created and queued for processing."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required knowledge:write permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"knowledge:write\"","schema":{"type":"string"}}}},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Upload a knowledge file","tags":["Knowledge"],"x-required-scope":"knowledge:write"}},"/knowledge/urls":{"post":{"description":"Adds a public HTTP or HTTPS URL and starts extraction and indexing. The returned document begins in processing status.","operationId":"createKnowledgeUrl","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeUrlCreate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocument"}}},"description":"The knowledge document was created and queued for processing."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required knowledge:write permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"knowledge:write\"","schema":{"type":"string"}}}},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Add a knowledge URL","tags":["Knowledge"],"x-required-scope":"knowledge:write"}},"/knowledge/{id}":{"delete":{"description":"Permanently deletes a knowledge document, its extracted content, and its search vectors.","operationId":"deleteKnowledgeDocument","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"204":{"description":"The knowledge document was deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required knowledge:write permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"knowledge:write\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Delete a knowledge document","tags":["Knowledge"],"x-required-scope":"knowledge:write"},"get":{"description":"Returns one knowledge document and its current ingestion and refresh status.","operationId":"retrieveKnowledgeDocument","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocument"}}},"description":"The knowledge document."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required knowledge:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"knowledge:read\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Retrieve a knowledge document","tags":["Knowledge"],"x-required-scope":"knowledge:read"},"patch":{"description":"Renames a knowledge document or enables or disables it for Agent search.","operationId":"updateKnowledgeDocument","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocumentUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocument"}}},"description":"The updated knowledge document."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required knowledge:write permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"knowledge:write\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Update a knowledge document","tags":["Knowledge"],"x-required-scope":"knowledge:write"}},"/knowledge/{id}/content":{"get":{"description":"Returns the extracted markdown currently indexed for the document. During a refresh, this remains the previous ready version until the replacement succeeds.","operationId":"retrieveKnowledgeDocumentContent","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"content":{"text/markdown":{"schema":{"type":"string"}}},"description":"The extracted markdown."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required knowledge:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"knowledge:read\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Retrieve knowledge content","tags":["Knowledge"],"x-required-scope":"knowledge:read"}},"/knowledge/{id}/refresh":{"post":{"description":"Starts a refresh of a URL knowledge document. Poll the document until refresh_status is no longer refreshing.","operationId":"refreshKnowledgeDocument","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocument"}}},"description":"The refresh was accepted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required knowledge:write permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"knowledge:write\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Refresh a knowledge document","tags":["Knowledge"],"x-required-scope":"knowledge:write"}},"/knowledge/{id}/schedule":{"patch":{"description":"Sets the automatic refresh interval for a URL knowledge document. Use zero to disable scheduled refreshes.","operationId":"updateKnowledgeDocumentSchedule","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocumentScheduleUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocument"}}},"description":"The knowledge document with its updated schedule."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required knowledge:write permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"knowledge:write\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Update a knowledge refresh schedule","tags":["Knowledge"],"x-required-scope":"knowledge:write"}},"/runs":{"get":{"description":"Returns model runs for the authenticated agent, ordered from newest to oldest. Provider-native raw usage payloads are never exposed.","operationId":"listRuns","parameters":[{"description":"The maximum number of objects to return. Defaults to 20 and is capped at 100.","in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"description":"An opaque cursor returned by the previous page.","in":"query","name":"after","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunList"}}},"description":"A page of runs."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required runs:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"runs:read\"","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"List runs","tags":["Runs"],"x-required-scope":"runs:read"}},"/runs/{id}":{"get":{"description":"Returns one model run that belongs to the authenticated agent.","operationId":"retrieveRun","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}},"description":"The run."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required runs:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"runs:read\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Retrieve a run","tags":["Runs"],"x-required-scope":"runs:read"}},"/users":{"get":{"description":"Returns users observed by the authenticated agent, ordered from most recently seen to oldest.","operationId":"listUsers","parameters":[{"description":"The maximum number of objects to return. Defaults to 20 and is capped at 100.","in":"query","name":"limit","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},{"description":"An opaque cursor returned by the previous page.","in":"query","name":"after","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserList"}}},"description":"A page of users."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required users:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"users:read\"","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"List users","tags":["Users"],"x-required-scope":"users:read"}},"/users/{id}":{"get":{"description":"Returns one user that belongs to the authenticated agent.","operationId":"retrieveUser","parameters":[{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}},"description":"The user."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"examples":{"insufficientScope":{"value":{"message":"This API key does not have the required users:read permission.","name":"insufficient_scope"}}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key does not have the required permission.","headers":{"WWW-Authenticate":{"description":"A Bearer challenge identifying the missing permission.","example":"Bearer realm=\"HeroUI Agents API\", error=\"insufficient_scope\", scope=\"users:read\"","schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"AgentApiKey":[]}],"summary":"Retrieve a user","tags":["Users"],"x-required-scope":"users:read"}}},"security":[{"AgentApiKey":[]}],"servers":[{"description":"Production","url":"https://api.heroui.pro/v1"}],"tags":[{"description":"People identified by your Agent integration.","name":"Users"},{"description":"Conversation metadata and message transcripts.","name":"Conversations"},{"description":"Model run status, usage, latency, and tool activity.","name":"Runs"},{"description":"Files and URLs the Agent can search for reference material.","name":"Knowledge"}]}