---
title: "Agent Catalog"
url: "https://real-estate-agency.apim.eu/apis/agent-catalog/versions/fa44b0ce-8be5-4345-b3ca-97adeccf8c16"
---

# Agent Catalog

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Agent Catalog","version":"1.0.0","description":"Turns structured agent metadata into a finished catalog entry - as a\ngovernance record and as a portal-style web view - and publishes it to\nthe internal Agent Catalog.\n\nA catalog entry always references exactly one agent from **Agent\nDeployments**. Standalone catalog entries without a deployment record are\nintentionally not supported, so compliance disclosures and rollout\nhistory stay maintained in a single place.\n\n## Workflow\n\n1. `POST /catalog-entries` starts the generation. The response carries `status: \"in_progress\"`.\n2. Once the entry is ready, the status changes to `completed`. We recommend\n   subscribing to the `catalog_entry.completed` event instead of polling.\n3. `GET /catalog-entries/{entryId}/record` returns the document.\n4. `POST /catalog-entries/{entryId}/publish` puts it live in the internal catalog.\n\n## Compliance disclosures\n\nBefore publication the API checks the disclosures required by governance\npolicy - most importantly the compliance-certification figures and the\nchargeback rate. If something is missing, the API responds with `422` and\n`code: \"compliance_disclosure_missing\"`.\n","contact":{"name":"API Support - Nexora AI","email":"api-support@nexora.example"},"license":{"name":"For demonstration purposes only"}},"servers":[{"url":"https://api.nexora.example/v1","description":"Production"},{"url":"https://sandbox.api.nexora.example/v1","description":"Sandbox"}],"tags":[{"name":"Catalog Entries"},{"name":"Templates"}],"security":[{"apiKey":[]}],"paths":{"/catalog-entries":{"get":{"tags":["Catalog Entries"],"summary":"List catalog entries","description":"Returns the catalog's entries, optionally filtered by agent and status.","operationId":"listCatalogEntries","parameters":[{"name":"agent_id","in":"query","description":"Only entries for this agent.","schema":{"type":"string","example":"agt_8f2c1a"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/CatalogEntryStatus"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"Cursor from `page.next_cursor` of the previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Results list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogEntry"}},"page":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["Catalog Entries"],"summary":"Create a catalog entry","description":"Starts the generation of a catalog entry from an agent and a\ntemplate. Processing runs asynchronously; the response initially\ncarries `status: \"in_progress\"`.\n","operationId":"createCatalogEntry","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCatalogEntryRequest"},"examples":{"standard":{"summary":"Copilot with the standard sections","value":{"agent_id":"agt_8f2c1a","template_id":"tpl_standard","target_team":"engineering","sections":["capabilities","data_scope","integrations","compliance"]}},"complianceAudience":{"summary":"Governance-focused version for the compliance review","value":{"agent_id":"agt_8f2c1a","template_id":"tpl_governance","target_team":"compliance-legal","sections":["capabilities","compliance","data_scope"]}}}}}},"responses":{"202":{"description":"Generation accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEntry"},"example":{"id":"entry_4d9b2e","agent_id":"agt_8f2c1a","template_id":"tpl_standard","target_team":"engineering","status":"in_progress","created_at":"2026-08-20T09:41:12Z"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/NotAuthenticated"},"403":{"$ref":"#/components/responses/ScopeMissing"},"404":{"description":"Agent or template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/catalog-entries/{entryId}":{"parameters":[{"$ref":"#/components/parameters/CatalogEntryId"}],"get":{"tags":["Catalog Entries"],"summary":"Retrieve a catalog entry","description":"Returns status, metadata and the compliance-disclosure report.","operationId":"getCatalogEntry","responses":{"200":{"description":"Catalog entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEntry"}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/catalog-entries/{entryId}/withdraw":{"parameters":[{"$ref":"#/components/parameters/CatalogEntryId"}],"post":{"tags":["Catalog Entries"],"summary":"Withdraw a catalog entry","description":"Takes a catalog entry off every channel and marks it `withdrawn`.\nThe record remains available for audit purposes.\n","operationId":"withdrawCatalogEntry","responses":{"204":{"description":"Withdrawn"},"401":{"$ref":"#/components/responses/NotAuthenticated"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/catalog-entries/{entryId}/record":{"parameters":[{"$ref":"#/components/parameters/CatalogEntryId"}],"get":{"tags":["Catalog Entries"],"summary":"Download the catalog entry record","description":"Returns the generated document. Only available once `status` is\n`completed` - before that the API responds with `409`.\n","operationId":"getCatalogEntryRecord","responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Generation not finished yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"conflict","message":"The catalog entry is still being generated.","details":[{"field":"status","reason":"in_progress"}]}}}}}}},"/catalog-entries/{entryId}/publish":{"parameters":[{"$ref":"#/components/parameters/CatalogEntryId"}],"post":{"tags":["Catalog Entries"],"summary":"Publish a catalog entry","description":"Puts the catalog entry live on the chosen channels. Compliance\ndisclosures are checked first.\n","operationId":"publishCatalogEntry","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channels"],"properties":{"channels":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CatalogChannel"}},"scheduled_for":{"type":"string","format":"date-time","description":"Optional time for a later, scheduled publication."}}},"example":{"channels":["internal_catalog","slack_directory","service_now_cmdb"]}}}},"responses":{"200":{"description":"Published, or scheduled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Publication"}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Compliance disclosures are missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"compliance_certification":{"summary":"Compliance-certification figures are missing","value":{"code":"compliance_disclosure_missing","message":"Compliance disclosures from the certification are missing for publication.","details":[{"field":"compliance_certification.data_classification_level","reason":"missing"},{"field":"compliance_certification.valid_until","reason":"expired"}]}},"chargeback":{"summary":"Chargeback rate exceeds the approved ceiling","value":{"code":"chargeback_rate_invalid","message":"The chargeback rate exceeds the business unit's approved ceiling.","details":[{"field":"chargeback.rate_percent","reason":"exceeds_ceiling"}]}}}}}}}}},"/templates":{"get":{"tags":["Templates"],"summary":"List templates","description":"The catalog's design templates, each with the sections it supports.","operationId":"listTemplates","responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}},"example":{"data":[{"id":"tpl_standard","name":"Standard","description":"Balanced layout covering capabilities, data scope, integrations and compliance.","sections":["capabilities","data_scope","integrations","compliance"]},{"id":"tpl_governance","name":"Governance","description":"Compliance-first layout for legal and governance review.","sections":["capabilities","compliance","data_scope"]}]}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"}}}}},"components":{"parameters":{"CatalogEntryId":{"name":"entryId","in":"path","required":true,"description":"Identifier of the catalog entry.","schema":{"type":"string","example":"entry_4d9b2e"}}},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Every call carries an API key in the `apikey` header. You generate the\nkey in the Nexora AI portal under \"My Apps\"; it's shown exactly once.\n\nEach key has the scopes it's allowed to use attached to it. If one is\nmissing, the API responds with `403` and `code: \"scope_missing\"`; the\nmissing scope is in `details[].field`.\n"}},"responses":{"NotAuthenticated":{"description":"Key is missing, revoked or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"not_authenticated","message":"The API key is invalid or has been revoked.","details":[]}}}},"ScopeMissing":{"description":"The key is missing a required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"scope_missing","message":"The API key is missing a required scope.","details":[{"field":"catalog:write","reason":"not_granted"}]}}}},"NotFound":{"description":"The catalog entry doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"The request doesn't match the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit reached","headers":{"Retry-After":{"schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Page":{"type":"object","description":"Cursor-based pagination.","properties":{"count":{"type":"integer","example":25},"total":{"type":"integer","example":138},"next_cursor":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","example":"compliance_certification.valid_until"},"reason":{"type":"string","example":"missing"}}},"Error":{"type":"object","description":"Uniform error format across all Nexora AI APIs.","required":["code","message"],"properties":{"code":{"type":"string","example":"compliance_disclosure_missing"},"message":{"type":"string","example":"Compliance disclosures from the certification are missing for publication."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"CatalogEntryStatus":{"type":"string","description":"Lifecycle of a catalog entry.","enum":["in_progress","completed","published","withdrawn","failed"],"example":"completed"},"CatalogChannel":{"type":"string","description":"Publication channel.","enum":["internal_catalog","slack_directory","service_now_cmdb","api_directory"]},"TargetTeam":{"type":"string","description":"Audience the entry is written for.","enum":["engineering","product","support","sales-ops","compliance-legal","open"],"default":"open"},"Section":{"type":"string","description":"Content block of the catalog entry.","enum":["capabilities","data_scope","integrations","compliance","target_teams","rollout_history"]},"CreateCatalogEntryRequest":{"type":"object","required":["agent_id","template_id"],"properties":{"agent_id":{"type":"string","description":"Agent the catalog entry is generated from.","example":"agt_8f2c1a"},"template_id":{"type":"string","description":"Design template of the catalog.","example":"tpl_standard"},"target_team":{"$ref":"#/components/schemas/TargetTeam"},"sections":{"type":"array","description":"Order and selection of sections. Defaults to the template's sections if omitted.","items":{"$ref":"#/components/schemas/Section"}},"internal_note":{"type":"string","maxLength":500,"description":"Internal remark; does not appear in the record.","example":"Owner wants the pilot renewed before the entry goes live org-wide."}}},"CatalogEntry":{"type":"object","properties":{"id":{"type":"string","example":"entry_4d9b2e"},"agent_id":{"type":"string","example":"agt_8f2c1a"},"template_id":{"type":"string","example":"tpl_standard"},"target_team":{"$ref":"#/components/schemas/TargetTeam"},"status":{"$ref":"#/components/schemas/CatalogEntryStatus"},"record_url":{"type":"string","format":"uri","description":"Only set once `status: completed`. The link is valid for 24 hours.","example":"https://api.nexora.example/v1/catalog-entries/entry_4d9b2e/record"},"pages":{"type":"integer","description":"Page count of the generated record.","example":4},"disclosures":{"$ref":"#/components/schemas/DisclosureReport"},"created_at":{"type":"string","format":"date-time","example":"2026-08-20T09:41:12Z"},"completed_at":{"type":"string","format":"date-time","nullable":true,"example":"2026-08-20T09:41:20Z"}}},"DisclosureReport":{"type":"object","description":"Result of the compliance-disclosure check.","properties":{"complete":{"type":"boolean","example":false},"missing":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"Publication":{"type":"object","properties":{"entry_id":{"type":"string","example":"entry_4d9b2e"},"status":{"$ref":"#/components/schemas/CatalogEntryStatus"},"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/CatalogChannel"},"state":{"type":"string","enum":["live","scheduled","failed"]},"url":{"type":"string","format":"uri"}}}},"published_at":{"type":"string","format":"date-time","example":"2026-08-20T09:44:03Z"}}},"Template":{"type":"object","properties":{"id":{"type":"string","example":"tpl_standard"},"name":{"type":"string","example":"Standard"},"description":{"type":"string","example":"Balanced layout covering capabilities, data scope, integrations and compliance."},"sections":{"type":"array","items":{"$ref":"#/components/schemas/Section"}}}}}}}
```