{"openapi":"3.1.0","info":{"title":"Aevah Public API Preview","version":"0.1.0-preview","summary":"Preview contract for governed Aevah platform resources.","description":"Aevah Public API Preview Specification. Publication describes the intended contract; it does not grant tenant access or imply that every operation is enabled in production. Confirm availability, scopes, hostnames, and limits with Aevah.","contact":{"name":"Aevah","email":"executive@aevah.com","url":"https://www.aevah.com/contact"},"license":{"name":"Proprietary"}},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","servers":[{"url":"https://{tenantHost}","description":"Tenant-specific API host assigned by Aevah; no public production host is advertised by this preview.","variables":{"tenantHost":{"default":"api.example.aevah.invalid","description":"Replace only with an Aevah-assigned hostname."}}}],"tags":[{"name":"Entities","description":"Governed enterprise entities and relationships."},{"name":"Definitions","description":"Semantic definitions, measures, and policies."},{"name":"Sources","description":"Governed source-system metadata and lineage entry points."},{"name":"Workflows","description":"Workflow definitions and tenant-authorized execution."},{"name":"Agents","description":"Agent definitions and tenant-authorized invocation."},{"name":"Decisions","description":"Recorded decisions and their context."},{"name":"Evidence","description":"Evidence and lineage supporting decisions and actions."}],"security":[{"oauth2":[]},{"bearerAuth":[]}],"paths":{"/entities":{"get":{"tags":["Entities"],"summary":"List entities","operationId":"listEntities","x-aevah-status":"preview","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A cursor-paginated collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Entity"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/entities/{id}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Entities"],"summary":"Get an entity","operationId":"getEntity","x-aevah-status":"preview","responses":{"200":{"description":"Entity found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/entities/{id}/relationships":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Entities"],"summary":"List an entity's relationships","operationId":"listEntityRelationships","x-aevah-status":"preview","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Relationships found.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Relationship"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/definitions":{"get":{"tags":["Definitions"],"summary":"List semantic definitions","operationId":"listDefinitions","x-aevah-status":"preview","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A cursor-paginated collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Definition"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/sources":{"get":{"tags":["Sources"],"summary":"List governed sources","operationId":"listSources","x-aevah-status":"preview","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A cursor-paginated collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/workflows":{"get":{"tags":["Workflows"],"summary":"List workflows","operationId":"listWorkflows","x-aevah-status":"preview","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A cursor-paginated collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/workflows/{id}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Workflows"],"summary":"Get a workflow","operationId":"getWorkflow","x-aevah-status":"preview","responses":{"200":{"description":"Workflow found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Workflows"],"summary":"Start a workflow","operationId":"startWorkflow","x-aevah-status":"preview","description":"Requires a tenant-authorized identity, the workflow execution scope, and an Idempotency-Key header. Authorization is evaluated against the workflow, inputs, and requested action.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvocationRequest"},"example":{"input":{"entityId":"ent_123"},"reason":"Review operational exception"}}}},"responses":{"202":{"description":"Workflow accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/agents":{"get":{"tags":["Agents"],"summary":"List agents","operationId":"listAgents","x-aevah-status":"preview","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A cursor-paginated collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/agents/{id}":{"parameters":[{"$ref":"#/components/parameters/ResourceId"}],"get":{"tags":["Agents"],"summary":"Get an agent","operationId":"getAgent","x-aevah-status":"preview","responses":{"200":{"description":"Agent found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Agents"],"summary":"Invoke an agent","operationId":"invokeAgent","x-aevah-status":"preview","description":"Requires a tenant-authorized identity, an invocation scope, an Idempotency-Key header, and policy approval for any downstream action.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvocationRequest"},"example":{"input":{"question":"Which exceptions require review?"},"reason":"Weekly operating review"}}}},"responses":{"202":{"description":"Invocation accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/decisions":{"get":{"tags":["Decisions"],"summary":"List decisions","operationId":"listDecisions","x-aevah-status":"preview","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A cursor-paginated collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Decision"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/evidence":{"get":{"tags":["Evidence"],"summary":"List evidence","operationId":"listEvidence","x-aevah-status":"preview","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A cursor-paginated collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"Tenant-specific OAuth 2.x/OIDC configuration. Authorization and token endpoints are supplied during onboarding and are intentionally not published here.","flows":{"authorizationCode":{"authorizationUrl":"https://identity.example.aevah.invalid/authorize","tokenUrl":"https://identity.example.aevah.invalid/token","scopes":{"aevah.read":"Read authorized tenant resources.","aevah.execute":"Invoke authorized workflows or agents."}},"clientCredentials":{"tokenUrl":"https://identity.example.aevah.invalid/token","scopes":{"aevah.read":"Read authorized tenant resources.","aevah.execute":"Invoke authorized workflows or agents."}}}},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant-issued access token. Availability and claims are tenant-specific."}},"parameters":{"ResourceId":{"name":"id","in":"path","required":true,"description":"Stable tenant-scoped resource identifier.","schema":{"type":"string","minLength":1}},"Limit":{"name":"limit","in":"query","description":"Maximum records to return.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"Cursor":{"name":"cursor","in":"query","description":"Opaque continuation cursor from a previous response.","schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique client-generated key used to make a mutation safe to retry.","schema":{"type":"string","minLength":16,"maxLength":255}}},"schemas":{"CollectionEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{}},"nextCursor":{"type":["string","null"]},"requestId":{"type":"string"}}},"Entity":{"type":"object","required":["id","type","displayName"],"properties":{"id":{"type":"string","examples":["ent_123"]},"type":{"type":"string","examples":["product"]},"displayName":{"type":"string","examples":["Example Product"]},"attributes":{"type":"object","additionalProperties":true},"definitionId":{"type":["string","null"]},"updatedAt":{"type":"string","format":"date-time"}}},"Relationship":{"type":"object","required":["id","type","fromEntityId","toEntityId"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"fromEntityId":{"type":"string"},"toEntityId":{"type":"string"},"attributes":{"type":"object","additionalProperties":true},"evidenceIds":{"type":"array","items":{"type":"string"}}}},"Definition":{"type":"object","required":["id","name","definition"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"definition":{"type":"string"},"owner":{"type":["string","null"]},"status":{"type":"string","enum":["draft","approved","retired"]}}},"Source":{"type":"object","required":["id","name","kind"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","examples":["erp"]},"status":{"type":"string","enum":["active","degraded","inactive"]},"lineageUri":{"type":["string","null"],"format":"uri"}}},"Workflow":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","retired"]},"requiredScopes":{"type":"array","items":{"type":"string"}}}},"Agent":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","retired"]},"capabilities":{"type":"array","items":{"type":"string"}},"requiredScopes":{"type":"array","items":{"type":"string"}}}},"Decision":{"type":"object","required":["id","summary","status"],"properties":{"id":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string","enum":["proposed","approved","rejected","executed"]},"owner":{"type":["string","null"]},"evidenceIds":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}}},"Evidence":{"type":"object","required":["id","kind","summary"],"properties":{"id":{"type":"string"},"kind":{"type":"string","examples":["lineage"]},"summary":{"type":"string"},"sourceId":{"type":["string","null"]},"observedAt":{"type":["string","null"],"format":"date-time"},"uri":{"type":["string","null"],"format":"uri"}}},"InvocationRequest":{"type":"object","required":["input","reason"],"properties":{"input":{"type":"object","additionalProperties":true},"reason":{"type":"string","minLength":1},"requestedBy":{"type":"string","description":"Optional caller correlation identifier; it does not override authenticated identity."}}},"Run":{"type":"object","required":["id","status","createdAt"],"properties":{"id":{"type":"string","examples":["run_123"]},"status":{"type":"string","enum":["queued","running","awaiting_review","completed","failed","cancelled"]},"createdAt":{"type":"string","format":"date-time"},"links":{"type":"object","additionalProperties":{"type":"string","format":"uri-reference"}}}},"Error":{"type":"object","required":["type","title","status","requestId"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"requestId":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"The request is malformed or fails validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Authentication is missing, expired, or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The identity is authenticated but not authorized for the tenant, resource, scope, or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The resource was not found or is intentionally concealed from this identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"The request conflicts with current state or reuses an idempotency key with different input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"The tenant or identity limit was exceeded. Honor Retry-After when present.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"An unexpected error occurred. Use requestId when contacting support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}