{ "openapi": "3.1.0", "info": { "title": "Helm API", "version": "1.0.0", "description": "The Helm API lets you query and relate data by entity type with flexible schemas. This guide covers the key concepts for querying data.\n\n## Authentication\n\nAll API requests require a **Personal Access Token (PAT)** using HTTP Basic Authentication.\n\nEncode your credentials as `Base64(client_id:client_secret)` and pass them in the `Authorization` header:\n\n```bash\n# Build the credentials token\nCREDENTIALS=$(echo -n \"${CLIENT_ID}:${CLIENT_SECRET}\" | base64)\n\n# Make an authenticated request\ncurl \"https://api.helm.bridge-labs.com/entity/entity-types\" \\\n -H \"Authorization: Basic ${CREDENTIALS}\"\n```\n\nEvery response uses standard HTTP status codes. A `401` means the token is missing or invalid.\n\n## Errors\n\nEvery error response uses a single consistent envelope:\n\n```json\n{\n \"error\": {\n \"status\": 422,\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Human-readable explanation\",\n \"details\": {}\n }\n}\n```\n\nThe HTTP status code is authoritative — `status` mirrors it for convenience.\n`code` is a stable machine-readable string and `details` is an\nerror-code-specific object. Common codes: `400` bad request, `401`\nunauthorized, `403` forbidden, `404` not found, `409` conflict (e.g. a\nduplicate `identifier_key` or a cardinality violation), `422` validation\nerror.\n\n## Pagination\n\nList endpoints and the query endpoint both support **offset pagination** with `page` and `limit`:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `page` | 1 | Page number (1-based) |\n| `limit` | 100 | Results per page (max 1000 on POST /query) |\n\nThe query endpoint also supports **keyset pagination** via `cursor`, which provides stable iteration over large result sets. Pass the `next_cursor` value from a previous response as the `cursor` field in your next request:\n\n```json\n{\n \"type_name\": \"Company\",\n \"cursor\": \"eyJpZCI6Ijg3Ni4uLiJ9\",\n \"limit\": 50\n}\n```\n\nUse `include_count: true` on POST /query to get the total number of matching entities in the `count` response field, capped at 10000 by default. To get the exact count, set `count_strategy` to `exact`.\n\n**When to use which:**\n- **Offset** (`page`) — simple browsing, jumping to arbitrary pages.\n- **Keyset** (`cursor`) — iterating through all results.\n\n## Filtering and Querying\n\nUse **POST /query** to search for entities of a specific entity type.\n\n### Filter structure\n\nFilters are composable. A **particle filter** targets a single field:\n\n```json\n{ \"operator\": \"eq\", \"path\": [\"attributes\", \"status\"], \"value\": \"active\" }\n```\n\nWrap particles in a **composite filter** to combine them with `and`, `or`, or `not`:\n\n```json\n{\n \"operator\": \"and\",\n \"filters\": [\n { \"operator\": \"eq\", \"path\": [\"attributes\", \"status\"], \"value\": \"active\" },\n { \"operator\": \"gte\", \"path\": [\"attributes\", \"revenue\"], \"value\": 100000 }\n ]\n}\n```\n\n### Path syntax\n\n| Path | Targets |\n|------|---------|\n| `[\"name\"]` | Entity name |\n| `[\"id\"]` | Entity ID |\n| `[\"type\", \"name\"]` | Entity type name |\n| `[\"attributes\", \"field\"]` | Top-level attribute |\n| `[\"created_at\"]` | Created timestamp |\n| `[\"relationships\", \"TypeName\", \"attributes\", \"field\"]` | Related entity attribute |\n\n### Operators\n\n| Operator | Description | Value type |\n|----------|-------------|------------|\n| `eq` | Equals | string, number |\n| `neq` | Not equals | string, number |\n| `is` | Is (boolean/null) | boolean, null |\n| `gt`, `gte`, `lt`, `lte` | Comparisons | string, number |\n| `in` | Value in array | string[], number[] |\n| `cs` | Array contains all | string[], number[] |\n| `ov` | Array overlaps (any match) | string[], number[] |\n| `like` | Pattern match (case-sensitive) | string (%, _) |\n| `ilike` | Pattern match (case-insensitive) | string (%, _) |\n| `fuzzy` | Approximate text match | string |\n\n### Sorting\n\nPass a `sort` array to control result order. Each entry specifies a `path` and `direction` (`asc`/`desc`):\n\n```json\n{\n \"sort\": [\n { \"path\": [\"attributes\", \"revenue\"], \"direction\": \"desc\" }\n ]\n}\n```\n\n## Working with Relationships\n\nEntities can be connected through **relationship rules**. To load related entities in a single request, use the `include` parameter on GET /entities/:id or POST /query.\n\n### Discovery workflow\n\n1. **Find available relationships** — call `GET /relationship-rules?entity_type_name=Company` to discover all rules where \"Company\" is either the source or target type.\n2. **Extract type names** — from each rule's `from_entity_type.name` and `to_entity_type.name`, collect the related type names (e.g. \"Vessel\", \"Person\").\n3. **Include in queries** — pass those names in the `include` array:\n\n### Relationship limits\n\nUse `max_relationships` to control how many related entities are returned per entity:\n\n| Endpoint | Default | Range |\n|----------|---------|-------|\n| GET /entities/:id | 1000 | 1–1000 |\n| POST /query | 100 | 1–1000 |\n\n### Response structure\n\nEach entry in the `relationships` array contains:\n\n```json\n{\n \"rule\": { \"id\": \"rule-uuid\", \"name\": \"Owns\" },\n \"entity\": {\n \"id\": \"related-uuid\",\n \"name\": \"Entity Name\",\n \"type\": { \"id\": \"type-uuid\", \"name\": \"Vessel\" },\n \"attributes\": { }\n },\n \"direction\": \"to\"\n}\n```\n\nThe `direction` field (`\"to\"` or `\"from\"`) indicates which side of the rule this entity is on.\n" }, "servers": [ { "url": "https://api.staging.bridge-labs-dev.com", "description": "Staging" }, { "url": "https://api.helm.bridge-labs.com", "description": "Production" }, { "url": "http://localhost:8000", "description": "Local Development" } ], "tags": [ { "name": "Entities", "description": "Entities are the core data objects in Helm. Each entity belongs to an **entity type**, has `attributes` JSON shaped by the entity type's schema and optional relationships to other entities.\n\nUse `POST /query` to search for entities by entity type." }, { "name": "Entity Types", "description": "Entity types define the structure and schema of entities. Each type is associated to a JSON schema that shapes an entity's `attributes` and configuration that determines what fields are sortable and searchable.\n\nList entity types to discover what schemas are available in your tenant and how their attributes are configured." }, { "name": "Relationship Rules", "description": "Relationship rules define how entity types can relate to each other (e.g. Company → Vessel). Use `GET /relationship-rules?entity_type_name=...` to discover which types are connected, then pass those type names in the `include` parameter when querying entities.\n\nSee the **Working with Relationships** guide above for the full discovery workflow." }, { "name": "Relationship Instances", "description": "Concrete relationships between entity instances" }, { "name": "Entity Artifacts", "description": "File storage for entity-attached artifacts" }, { "name": "Entity Type Sharing", "description": "Owner-side cross-tenant shares, entity data-shares, and intra-tenant grants on an entity type." }, { "name": "Entity Sharing", "description": "Owner-side cross-tenant shares on an individual entity." }, { "name": "Relationship Rule Sharing", "description": "Owner-side cross-tenant shares and intra-tenant grants on a relationship rule." }, { "name": "Query", "description": "The query endpoint provides advanced entity search with composite filters (`and`/`or`/`not`), multi-column sorting, keyset and offset pagination, relationship inclusion, total counts, and distinct-on grouping.\n\nSee the **Filtering and Querying** guide above for filter syntax and examples." }, { "name": "Events", "description": "System event publishing and querying" }, { "name": "Workflow Definitions", "description": "Workflow lifecycle and configuration" }, { "name": "Job Definitions", "description": "Reusable job definitions with versioning" }, { "name": "App Specs", "description": "Bridge app spec definitions" }, { "name": "Workflow Sharing", "description": "Owner-side cross-tenant shares + grants" }, { "name": "Job Sharing", "description": "Owner-side cross-tenant shares + grants" }, { "name": "App Spec Sharing", "description": "Owner-side cross-tenant shares + grants" }, { "name": "Schemas", "description": "JSON schemas define the structure and shape of resources." }, { "name": "Validation", "description": "Validate data against a JSON Schema." }, { "name": "Schema Sharing", "description": "Owner-side management of cross-tenant shares and grants for JSON schema catalog items." }, { "name": "Config", "description": "Tenant-scoped app_config (1:1 per spec)" }, { "name": "Integrations", "description": "Per-provider integrations bound to the tenant's app_config" }, { "name": "Tokens", "description": "App tokens per integration (rotate-on-issue, list, revoke)" }, { "name": "Principals", "description": "Per-company / team / user overrides on top of spec defaults" }, { "name": "App Roles", "description": "Tenant-admin assignment of users to spec-defined policy roles by key" }, { "name": "Run", "description": "External-provider render entry point" }, { "name": "Workflow Runs", "description": "Trigger, retry, and cancel workflow runs" }, { "name": "Workflow Run Queries", "description": "Query workflow, job, and action run history" }, { "name": "Schedules", "description": "Cron-based workflow scheduling" }, { "name": "Workflow Activation", "description": "Per-tenant workflow lifecycle: activate, config, and trigger management" }, { "name": "Users", "description": "Read-only tenant directory" }, { "name": "Roles", "description": "System + tenant role catalogue" }, { "name": "Role Assignments", "description": "Bind / revoke roles for users in this tenant" }, { "name": "Policies", "description": "Tenant-scoped access_policy CRUD plus per-policy grants" }, { "name": "Grants", "description": "Intra-tenant resource_access_grant admin view" }, { "name": "Shares", "description": "Inbound + outbound resource_share admin view" }, { "name": "External Users", "description": "Tenant-admin pre-provisioning + soft-deactivation of external_user rows" }, { "name": "External Companies", "description": "Read-only tenant view of provisioned external_company rows" }, { "name": "API Tokens", "description": "Tenant-scoped api_token lifecycle (mint, revoke, policy attach)" }, { "name": "Manifests", "description": "Policy manifest CRUD plus the publication / subscription lifecycle" }, { "name": "Secrets", "description": "Tenant-scope secret values (`scope=tenant`, resolves as `{{ secrets.tenant. }}`). Per-user / per-company / per-team secrets are written from inside a running app via the `setSecret` step, not via this admin surface. See `docs/guides/SECRETS-HOWTO.md`." }, { "name": "Me", "description": "Self-scoped reads for the current caller (advisory permission snapshot used by the docs portal's spec filter)" }, { "name": "Authentication", "description": "Public token exchange (no auth required)" }, { "name": "Token Management", "description": "API token CRUD and usage tracking" } ], "x-tagGroups": [ { "name": "Entities", "tags": [ "Entities", "Entity Types", "Relationship Rules", "Relationship Instances", "Entity Artifacts", "Entity Type Sharing", "Entity Sharing", "Relationship Rule Sharing", "Query", "Events" ] }, { "name": "Definitions", "tags": [ "Workflow Definitions", "Job Definitions", "App Specs", "Workflow Sharing", "Job Sharing", "App Spec Sharing" ] }, { "name": "Schemas", "tags": [ "Schemas", "Validation", "Schema Sharing" ] }, { "name": "Apps", "tags": [ "Config", "Integrations", "Tokens", "Principals", "App Roles", "Run" ] }, { "name": "Workflows", "tags": [ "Workflow Runs", "Workflow Run Queries", "Schedules", "Workflow Activation" ] }, { "name": "Access", "tags": [ "Users", "Roles", "Role Assignments", "Policies", "Grants", "Shares", "External Users", "External Companies", "API Tokens", "Manifests", "Secrets", "Me" ] }, { "name": "Auth", "tags": [ "Authentication", "Token Management" ] } ], "paths": { "/entity/entities": { "get": { "operationId": "listEntities", "summary": "List entities by type", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "description": "Retrieve entities filtered by type name or type ID. Supports offset pagination with `page` and `limit`, and optional relationship loading via the `include` parameter.\n\nFor complex filtering, sorting, or keyset pagination, use **POST /query** instead.", "x-permission": [ { "resource": "entity", "action": "read" } ], "parameters": [ { "name": "type_name", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, { "name": "include", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "include_specs", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "max_relationships", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "List of entities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEntitiesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createEntity", "summary": "Create a new entity", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "description": "Create one entity by key. Internally an upsert with `on_conflict='raise'`, so this returns **409** if the entity type's computed `identifier_key` already matches a live entity. Emits a `created` event (dispatched to triggers/workflows).", "x-permission": [ { "resource": "entity", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEntity" } } } }, "responses": { "201": { "description": "Created entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEntityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An entity with the same identifier_key already exists." }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}": { "get": { "operationId": "getEntity", "summary": "Get entity by ID", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "description": "Fetch a single entity by its UUID. Use the `include` query parameter to load related entities by type name (e.g. `?include=Vessel,Person`), or `include_rule_ids` to include by specific rule IDs.\n\nControl the number of returned relationships per entity with `max_relationships` (default 1000, max 1000).", "x-permission": [ { "resource": "entity", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "include_specs", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "include_rule_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "max_relationships", "in": "query", "required": false, "schema": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "Entity details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEntityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Entity not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateEntity", "summary": "Replace entity attributes", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "description": "Full by-id replace: `attributes` overwrite the existing object and the `identifier_key` is recomputed from them. Accepts the rekey-merge knobs `merge_on_conflict` (default true) and `merge_cardinality` (`raise`|`trim`): if the recomputed key collides with a different live entity, the targeted entity survives and absorbs the incumbent (relationships + artifacts re-pointed, incumbent soft-deleted, a `merged` event recorded). With `merge_on_conflict:false` the collision is rejected **409**. No event fires if nothing changed.", "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEntity" } } } }, "responses": { "200": { "description": "Updated entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEntityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Entity not found" }, "409": { "description": "Rekey collided and merge_on_conflict was false." }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteEntity", "summary": "Delete an entity", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "description": "Soft-delete: sets `deleted_at` rather than removing the row (a separate archival process hard-deletes later). Cascades — the entity's relationships, its storage artifacts, and its indexed-attribute extension row are soft-deleted/cleaned too. Emits a `deleted` event, always `suppressed` (audit only — no trigger/workflow fired).", "x-permission": [ { "resource": "entity", "action": "delete" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" } ], "responses": { "200": { "description": "Delete result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEntityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Entity not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}/attributes": { "patch": { "operationId": "patchEntityAttributes", "summary": "Merge-patch entity attributes", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "description": "Shallow-merges the supplied fields into the entity's existing `attributes` (`{...existing, ...patch}`); set a field to `null` to remove it. Write is a compare-and-swap on `updated_at` — if the row changed since it was read you get **409 `CONCURRENT_MODIFICATION`**. The `identifier_key` is recomputed from the merged attributes, so a patch can also trigger a rekey-merge (merge defaults on).", "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchEntityAttributes" } } } }, "responses": { "200": { "description": "Patched entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEntityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Entity not found" }, "409": { "description": "`CONCURRENT_MODIFICATION` — the entity changed since it was read (compare-and-swap on updated_at failed)." }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/upsert": { "post": { "operationId": "upsertEntities", "summary": "Upsert multiple entities", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "description": "Bulk create/update — the settings-rich entity write path.\n\n**Match mode is per row.** A row without `id` is matched **by key** (`identifier_key`, derived from attributes); a row WITH `id` is matched **by id** (UUID, 404 if missing). `on_conflict` (`raise`|`ignore`|`merge`|`replace`, default `replace`) applies to BY-KEY rows that hit an existing entity: `raise`→409 (whole batch); `ignore`→leave as-is; `merge`→shallow JSONB merge of attributes; `replace`→full attribute replace. By-id rows always full-replace + recompute the key and **ignore `on_conflict`**.\n\n**Rekey-merge** (`merge_on_conflict` default true, `merge_cardinality` `raise`|`trim`) governs by-id rows whose recomputed key collides with a different live entity: merge (survivor absorbs incumbent) or reject 409. `merge_cardinality:raise` surfaces as **422** if re-pointing would exceed a relationship rule cap; `trim` soft-deletes the oldest edges.\n\n**Inline relationships** (`data[].relationships[]`) resolve their target by `target_entity_id` OR `target_identifier` + `target_type_name`, where `target_identifier` is an object of the target type's `identifier_key` attributes — supporting single- (`{port_code}`) and multi-attribute (`{imo_number,name}`) keys; unresolved targets are reported in the response errors.\n\nValidates every input row up front against the entity type's schema (chunked into 2000-row schema-service calls), then commits in 1000-row batches; within a batch rows are deduped (last wins per id/key). A single invalid row anywhere in `data` aborts with HTTP 422 and no DB writes. Capped at 100,000 rows per request.", "x-permission": [ { "resource": "entity", "action": "update" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertEntities" } } } }, "responses": { "200": { "description": "Upserted entities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertEntitiesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation failed (schema, identifier, or row-count cap) — no rows were committed." }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/bulk-delete": { "post": { "operationId": "bulkDeleteEntities", "summary": "Delete multiple entities by ID", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "description": "Soft-delete up to 100 entities by id (same cascade as single delete: relationships, artifacts, and indexed-attribute rows are cleaned). `deleted` events are always `suppressed` (audit only).", "x-permission": [ { "resource": "entity", "action": "delete" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteEntities" } } } }, "responses": { "200": { "description": "Bulk delete result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteEntitiesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/import": { "post": { "operationId": "bulkImportEntitiesFromCsv", "summary": "Bulk import entities from a CSV stream", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "description": "Accepts a CSV body with import configuration in the X-Import-Config header (URL-encoded JSON). The full stream is parsed and buffered, then validated against the entity type's schema before any DB write fires — a single invalid row anywhere in the file aborts the import with HTTP 422 and no rows are committed. After validation passes, rows commit in 1000-row batches. Capped at 100,000 rows per request — larger imports must be split into multiple requests.", "x-permission": [ { "resource": "entity", "action": "create" } ], "parameters": [ { "name": "X-Import-Config", "in": "header", "required": false, "description": "URL-encoded JSON with entity_type_id/name, on_conflict, delimiter, column_mapping, etc. (shape: BulkImportCsv).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Import result summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportCsvResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Validation failed (schema, identifier, or row-count cap) — no rows were committed." }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/export": { "post": { "operationId": "bulkExportEntitiesToCsv", "summary": "Export entities to a CSV stream", "tags": [ "Entities" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "read" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkExportCsv" } } } }, "responses": { "200": { "description": "CSV stream (text/csv)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}/artifacts/upload-url": { "post": { "operationId": "createArtifactUploadUrl", "summary": "Create a signed upload URL for an artifact", "tags": [ "Entity Artifacts" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadUrlRequest" } } } }, "responses": { "201": { "description": "Upload URL and artifact metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadUrlResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}/artifacts/{artifactId}/confirm": { "post": { "operationId": "confirmArtifactUpload", "summary": "Confirm an artifact upload after uploading to storage", "tags": [ "Entity Artifacts" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Artifact ID" }, "description": "Artifact ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "checksum": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Confirmed artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmUploadResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}/artifacts": { "get": { "operationId": "listEntityArtifacts", "summary": "List artifacts for an entity", "tags": [ "Entity Artifacts" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" }, { "name": "artifact_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "artifact_type_in", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, { "name": "include_versions", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of artifacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEntityArtifactsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}/artifacts/{artifactId}": { "get": { "operationId": "downloadArtifact", "summary": "Download an artifact binary", "tags": [ "Entity Artifacts" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Artifact ID" }, "description": "Artifact ID" } ], "responses": { "200": { "description": "Binary stream with Content-Type header" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Artifact not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteArtifact", "summary": "Delete a single artifact", "tags": [ "Entity Artifacts" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Artifact ID" }, "description": "Artifact ID" } ], "responses": { "200": { "description": "Artifact deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Artifact not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}/artifacts/{artifactId}/download-url": { "get": { "operationId": "getArtifactDownloadUrl", "summary": "Get a signed download URL for an artifact", "tags": [ "Entity Artifacts" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" }, { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Artifact ID" }, "description": "Artifact ID" } ], "responses": { "200": { "description": "Download URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDownloadUrlResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Artifact not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}/artifacts/bulk-delete": { "post": { "operationId": "bulkDeleteEntityArtifacts", "summary": "Delete all artifacts of a given type for an entity", "tags": [ "Entity Artifacts" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "description": "Entity ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteEntityArtifactsRequest" } } } }, "responses": { "200": { "description": "Bulk delete result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteEntityArtifactsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}/shares": { "get": { "operationId": "listEntitySharingShares", "summary": "List shares for this resource (owner view)", "tags": [ "Entity Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Shares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createEntitySharingShare", "summary": "Create a share for this resource", "tags": [ "Entity Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShare" } } } }, "responses": { "201": { "description": "Share created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entities/{id}/shares/{shareId}": { "put": { "operationId": "updateEntitySharingShare", "summary": "Update a share", "tags": [ "Entity Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShare" } } } }, "responses": { "200": { "description": "Share updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteEntitySharingShare", "summary": "Delete a share", "tags": [ "Entity Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Share deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types": { "get": { "operationId": "listEntityTypes", "summary": "List entity types", "tags": [ "Entity Types" ], "security": [ { "BasicAuth": [] } ], "description": "List all entity type definitions in the current tenant. Each type includes its indexed attribute configuration, which determines which attributes can be used in filters and sorting.\n\nFilter by `status` (active/inactive) or `name` (case-insensitive).", "x-permission": [ { "resource": "entity_type", "action": "read" } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "active", "deprecated", "inactive", "archived" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "List of entity types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEntityTypesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createEntityType", "summary": "Create a new entity type", "tags": [ "Entity Types" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEntityType" } } } }, "responses": { "201": { "description": "Created entity type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEntityTypeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types/{id}": { "get": { "operationId": "getEntityType", "summary": "Get entity type by ID", "tags": [ "Entity Types" ], "security": [ { "BasicAuth": [] } ], "description": "Retrieve the full definition of an entity type, including its attribute configuration with indexed field names, types, and derivation rules.", "x-permission": [ { "resource": "entity_type", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity Type ID" }, "description": "Entity Type ID" } ], "responses": { "200": { "description": "Entity type details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEntityTypeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Entity type not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateEntityType", "summary": "Update an entity type", "tags": [ "Entity Types" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity Type ID" }, "description": "Entity Type ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEntityType" } } } }, "responses": { "200": { "description": "Updated entity type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEntityTypeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Entity type not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types/{id}/config": { "patch": { "operationId": "patchEntityTypeConfig", "summary": "Patch entity type configuration", "tags": [ "Entity Types" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity Type ID" }, "description": "Entity Type ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchEntityTypeConfig" } } } }, "responses": { "200": { "description": "Updated entity type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEntityTypeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Entity type not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types/{id}/sync-status": { "get": { "operationId": "getSyncStatus", "summary": "Get ext table sync status for an entity type", "tags": [ "Entity Types" ], "security": [ { "BasicAuth": [] } ], "description": "Returns the most recent reindex job for this entity type. Shows progress of automatic or manual ext table backfills.", "x-permission": [ { "resource": "entity_type", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity Type ID" }, "description": "Entity Type ID" } ], "responses": { "200": { "description": "Sync status (null data if no jobs exist)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types/{id}/shares": { "get": { "operationId": "listEntityTypeSharingShares", "summary": "List shares for this resource (owner view)", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Shares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createEntityTypeSharingShare", "summary": "Create a share for this resource", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShare" } } } }, "responses": { "201": { "description": "Share created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types/{id}/shares/{shareId}": { "put": { "operationId": "updateEntityTypeSharingShare", "summary": "Update a share", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShare" } } } }, "responses": { "200": { "description": "Share updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteEntityTypeSharingShare", "summary": "Delete a share", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Share deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types/{id}/data-shares": { "get": { "operationId": "listEntityTypeSharingDataShares", "summary": "List datashares for this resource (owner view)", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "DataShares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createEntityTypeSharingDataShare", "summary": "Create a datashare for this resource", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShare" } } } }, "responses": { "201": { "description": "DataShare created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types/{id}/data-shares/{shareId}": { "put": { "operationId": "updateEntityTypeSharingDataShare", "summary": "Update a datashare", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShare" } } } }, "responses": { "200": { "description": "DataShare updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteEntityTypeSharingDataShare", "summary": "Delete a datashare", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "DataShare deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types/{id}/grants": { "get": { "operationId": "listEntityTypeSharingGrants", "summary": "List grants for this resource (owner view)", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Grants" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createEntityTypeSharingGrant", "summary": "Create a grant for this resource", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResourceGrant" } } } }, "responses": { "201": { "description": "Grant created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/entity-types/{id}/grants/{grantId}": { "put": { "operationId": "updateEntityTypeSharingGrant", "summary": "Update a grant", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGrant" } } } }, "responses": { "200": { "description": "Grant updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteEntityTypeSharingGrant", "summary": "Delete a grant", "tags": [ "Entity Type Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "entity_type", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Grant deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationship-rules": { "get": { "operationId": "listRelationshipRules", "summary": "List relationship rules", "tags": [ "Relationship Rules" ], "security": [ { "BasicAuth": [] } ], "description": "List relationship rules with optional filtering. Use `entity_type_name` to discover all rules where a given type appears as either source or target — this is the recommended way to find which entity types are related before using the `include` parameter on entity endpoints.", "x-permission": [ { "resource": "relationship_rule", "action": "read" } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "name_in", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "from_entity_type_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "to_entity_type_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "entity_type_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "active", "deprecated", "inactive", "archived" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "List of relationship rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRelationshipRulesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createRelationshipRule", "summary": "Create a new relationship rule", "tags": [ "Relationship Rules" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRelationshipRule" } } } }, "responses": { "201": { "description": "Created relationship rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRelationshipRuleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationship-rules/{id}": { "get": { "operationId": "getRelationshipRule", "summary": "Get relationship rule by ID", "tags": [ "Relationship Rules" ], "security": [ { "BasicAuth": [] } ], "description": "Retrieve the full details of a relationship rule, including source/target entity types, cardinality constraints (`max_from_cardinality`, `max_to_cardinality`), semantic labels, and symmetry configuration.", "x-permission": [ { "resource": "relationship_rule", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Relationship Rule ID" }, "description": "Relationship Rule ID" } ], "responses": { "200": { "description": "Relationship rule details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRelationshipRuleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Relationship rule not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateRelationshipRule", "summary": "Update a relationship rule", "tags": [ "Relationship Rules" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Relationship Rule ID" }, "description": "Relationship Rule ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRelationshipRule" } } } }, "responses": { "200": { "description": "Updated relationship rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRelationshipRuleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Relationship rule not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationship-rules/{id}/shares": { "get": { "operationId": "listRelationshipRuleSharingShares", "summary": "List shares for this resource (owner view)", "tags": [ "Relationship Rule Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Shares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createRelationshipRuleSharingShare", "summary": "Create a share for this resource", "tags": [ "Relationship Rule Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShare" } } } }, "responses": { "201": { "description": "Share created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationship-rules/{id}/shares/{shareId}": { "put": { "operationId": "updateRelationshipRuleSharingShare", "summary": "Update a share", "tags": [ "Relationship Rule Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShare" } } } }, "responses": { "200": { "description": "Share updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteRelationshipRuleSharingShare", "summary": "Delete a share", "tags": [ "Relationship Rule Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Share deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationship-rules/{id}/grants": { "get": { "operationId": "listRelationshipRuleSharingGrants", "summary": "List grants for this resource (owner view)", "tags": [ "Relationship Rule Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Grants" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createRelationshipRuleSharingGrant", "summary": "Create a grant for this resource", "tags": [ "Relationship Rule Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResourceGrant" } } } }, "responses": { "201": { "description": "Grant created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationship-rules/{id}/grants/{grantId}": { "put": { "operationId": "updateRelationshipRuleSharingGrant", "summary": "Update a grant", "tags": [ "Relationship Rule Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGrant" } } } }, "responses": { "200": { "description": "Grant updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteRelationshipRuleSharingGrant", "summary": "Delete a grant", "tags": [ "Relationship Rule Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_rule", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Grant deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationships": { "get": { "operationId": "listRelationshipInstances", "summary": "List relationship instances", "tags": [ "Relationship Instances" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_instance", "action": "read" } ], "parameters": [ { "name": "from_entity_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "to_entity_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "rule_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "rule_name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "List of relationship instances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRelationshipInstancesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createRelationshipInstance", "summary": "Create a relationship instance", "tags": [ "Relationship Instances" ], "security": [ { "BasicAuth": [] } ], "description": "Cardinality violations under `on_cardinality_violation: \"raise\"` return HTTP 409 Conflict (`Cardinality constraint violated`). The `\"ignore\"` strategy silently no-ops on violation and returns HTTP 422 with an actionable message (never 503).", "x-permission": [ { "resource": "relationship_instance", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRelationshipInstance" } } } }, "responses": { "201": { "description": "Created relationship instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRelationshipInstanceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict — relationship instance already exists OR cardinality constraint violated under on_cardinality_violation:\"raise\" (max_from_cardinality / max_to_cardinality exceeded)." }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationships/upsert": { "post": { "operationId": "upsertRelationshipInstances", "summary": "Upsert multiple relationship instances", "tags": [ "Relationship Instances" ], "security": [ { "BasicAuth": [] } ], "description": "Batch upsert. `on_conflict` selects per-row behaviour on duplicate (rule_id, from, to) tuples; `on_cardinality_violation` selects per-row behaviour on max_from / max_to overflow. `\"raise\"` on either knob → 409 Conflict; other strategies absorb the violation.", "x-permission": [ { "resource": "relationship_instance", "action": "update" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertRelationshipInstances" } } } }, "responses": { "200": { "description": "Upserted relationship instances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertRelationshipInstancesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict — relationship instance already exists (under on_conflict:\"raise\") OR cardinality constraint violated under on_cardinality_violation:\"raise\" (max_from_cardinality / max_to_cardinality exceeded)." }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationships/set": { "post": { "operationId": "setRelationshipInstances", "summary": "Set-replace an entity's relationships under one rule", "tags": [ "Relationship Instances" ], "security": [ { "BasicAuth": [] } ], "description": "SET-REPLACE: after the call the entity's relationship instances on the given `direction` side for the rule are exactly `target_ids` — unlisted ones removed, missing ones created, present ones kept. The diff and both mutations run in one atomic DB transaction. A `target_ids` list exceeding the rule's cardinality returns 409.", "x-permission": [ { "resource": "relationship_instance", "action": "update" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRelationshipInstances" } } } }, "responses": { "200": { "description": "Set-replace counts (added / removed / kept)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRelationshipInstancesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Relationship rule or entity not found" }, "409": { "description": "Conflict — `target_ids` exceeds the rule's max_from_cardinality / max_to_cardinality." }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationships/bulk-delete": { "post": { "operationId": "bulkDeleteRelationshipInstances", "summary": "Bulk delete relationship instances", "tags": [ "Relationship Instances" ], "security": [ { "BasicAuth": [] } ], "description": "Soft deletes multiple relationship instances by their IDs. Delete events are stored for audit but not dispatched.", "x-permission": [ { "resource": "relationship_instance", "action": "delete" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteRelationshipInstances" } } } }, "responses": { "200": { "description": "Bulk delete results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteRelationshipInstancesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "One or more relationship instances not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/relationships/{id}": { "get": { "operationId": "getRelationshipInstance", "summary": "Get relationship instance by ID", "tags": [ "Relationship Instances" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_instance", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Relationship Instance ID" }, "description": "Relationship Instance ID" } ], "responses": { "200": { "description": "Relationship instance details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRelationshipInstanceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Relationship instance not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteRelationshipInstance", "summary": "Delete a relationship instance", "tags": [ "Relationship Instances" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "relationship_instance", "action": "delete" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Relationship Instance ID" }, "description": "Relationship Instance ID" }, { "name": "suppress_events", "in": "query", "required": false, "schema": { "default": true, "type": "boolean" } } ], "responses": { "200": { "description": "Delete result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRelationshipInstanceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Relationship instance not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/query": { "post": { "operationId": "queryEntities", "summary": "Query entities with filters, sorting, and pagination", "tags": [ "Query" ], "security": [ { "BasicAuth": [] } ], "description": "Flexible entity query endpoint. Supports composite filters (and/or/not with particle operators like eq, in, like, fuzzy), multi-column sorting, keyset pagination via cursor, offset pagination via page, relationship inclusion, total count, and distinct-on grouping.\n\n**Pagination:** Use `cursor` (from a previous response's `next_cursor`) for stable keyset pagination, or `page` for offset pagination. Cannot combine `cursor` with `page > 1`.\n\n**Filters:** Pass a single particle filter or a composite filter with `and`/`or`/`not` logic. Particle filter operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `cs`, `like`, `ilike`, `ov`, `segment`, `fuzzy`, `is`.\n\n**Relationships:** Use `include` to load related entities by relationship rule name. Control max per entity with `max_relationships`.\n\n**Distinct:** Use `distinct_on` to return one entity per unique combination of attribute paths (SELECT DISTINCT ON).", "x-permission": [ { "resource": "entity", "action": "read" }, { "resource": "entity_type", "action": "read" }, { "resource": "relationship_instance", "action": "read" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryFilters" } } } }, "responses": { "200": { "description": "Paginated query results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/query/distinct": { "post": { "operationId": "queryDistinctValues", "summary": "Get distinct values for an indexed attribute", "tags": [ "Query" ], "security": [ { "BasicAuth": [] } ], "description": "Returns an array of unique values for a specific indexed attribute on an entity type. Useful for building filter dropdowns, autocomplete, and faceted search UIs.\n\nOnly works with attributes that have been configured as indexed in the entity type's attribute configuration.", "x-permission": [ { "resource": "entity", "action": "read" }, { "resource": "entity_type", "action": "read" }, { "resource": "relationship_instance", "action": "read" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistinctValuesRequest" } } } }, "responses": { "200": { "description": "Array of distinct attribute values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistinctValuesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/query-graph": { "post": { "operationId": "queryEntityGraph", "summary": "Query an entity graph with deep relationship hydration", "tags": [ "Query" ], "security": [ { "BasicAuth": [] } ], "description": "Returns a root entity set plus every reachable related entity in one deduplicated graph payload (`roots` / `nodes` / `edges`). Nested `include` levels are hydrated server-side under a node budget; the `page_info.truncations` array reports any branch constrained by that budget.", "x-permission": [ { "resource": "entity", "action": "read" }, { "resource": "entity_type", "action": "read" }, { "resource": "relationship_instance", "action": "read" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type_name": { "type": "string" }, "filter": { "default": { "operator": "and", "filters": [] }, "anyOf": [ { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "and", "or", "not" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ParticleFilter" }, { "$ref": "#/components/schemas/__schema0" } ] } } }, "required": [ "operator", "filters" ], "additionalProperties": false }, { "$ref": "#/components/schemas/ParticleFilter" } ] }, "sort": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/SortSpec" } }, "include": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } }, "limit": { "default": 100, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 }, "page": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "cursor": { "type": "string" }, "include_count": { "default": false, "type": "boolean" }, "count_strategy": { "default": "capped", "type": "string", "enum": [ "exact", "estimate", "capped" ], "description": "How the total count is computed — exact (full count), estimate (planner estimate, fast on large sets), capped (counts up to the cap, default 10000)." } }, "required": [ "type_name", "sort", "include", "limit", "page", "include_count", "count_strategy" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Deduplicated entity graph", "content": { "application/json": { "schema": { "type": "object", "properties": { "roots": { "type": "array", "items": { "type": "string" } }, "nodes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "identifier_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attributes": { "type": "object", "additionalProperties": {} }, "type": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "identifier_key", "attributes", "type", "created_at", "updated_at" ], "additionalProperties": false } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from_entity_id": { "type": "string" }, "to_entity_id": { "type": "string" }, "rule_id": { "type": "string" }, "rule_name": { "type": "string" }, "direction": { "type": "string", "enum": [ "from", "to" ] } }, "required": [ "from_entity_id", "to_entity_id", "rule_id", "direction" ], "additionalProperties": false } }, "page_info": { "type": "object", "properties": { "total_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "next_cursor": { "type": "string" }, "has_more": { "type": "boolean" }, "truncated": { "type": "boolean" }, "truncations": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "type_name": { "type": "string" }, "depth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "requested_limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "applied_limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "type": "string", "const": "node_budget" } }, "required": [ "path", "type_name", "depth", "requested_limit", "applied_limit", "reason" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "roots", "nodes", "edges", "page_info" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/graphql/schema": { "get": { "operationId": "getGraphqlSchema", "summary": "Get the tenant-scoped GraphQL schema", "tags": [ "Query" ], "security": [ { "BasicAuth": [] } ], "description": "Returns the GraphQL schema derived from this tenant's entity-type and relationship-rule catalogues. Defaults to standard introspection JSON (`{ data: { __schema: { ... } } }`) for GraphQL clients; pass `?sdl=1` to receive the schema rendered as SDL (text/plain).", "x-permission": [ { "resource": "entity", "action": "read" }, { "resource": "entity_type", "action": "read" }, { "resource": "relationship_instance", "action": "read" } ], "parameters": [ { "name": "sdl", "in": "query", "required": false, "schema": { "description": "When set to `1`, return the schema as SDL (text/plain).", "type": "string", "enum": [ "1" ] }, "description": "When set to `1`, return the schema as SDL (text/plain)." } ], "responses": { "200": { "description": "Introspection JSON (default) or SDL text (`?sdl=1`)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/entity/graphql": { "post": { "operationId": "runGraphqlQuery", "summary": "Run a tenant-scoped GraphQL query", "tags": [ "Query" ], "security": [ { "BasicAuth": [] } ], "description": "Executes a GraphQL query against this tenant's entity graph. Returns the query `data` on success. Parse / validation / bad-input errors return HTTP 400; execution-time engine errors return HTTP 422.", "x-permission": [ { "resource": "entity", "action": "read" }, { "resource": "entity_type", "action": "read" }, { "resource": "relationship_instance", "action": "read" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The GraphQL query document." }, "variables": { "description": "Variable values referenced by the query document.", "type": "object", "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "GraphQL query result data" }, "400": { "description": "GraphQL parse / validation / bad-input error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "GraphQL execution error (valid document, engine refused)" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/event/events": { "get": { "operationId": "listEvents", "summary": "List system events", "tags": [ "Events" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "entity_type_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "entity_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "List of events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/event/events/{id}": { "get": { "operationId": "getEvent", "summary": "Get a system event by ID", "tags": [ "Events" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Event ID" }, "description": "Event ID" } ], "responses": { "200": { "description": "Event details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEventResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Event not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/workflows": { "post": { "operationId": "createWorkflowDefinition", "summary": "Create a new workflow definition", "tags": [ "Workflow Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "label": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "default": "draft", "$ref": "#/components/schemas/ItemLifecycleStatus" }, "source_yaml": { "type": "string", "minLength": 1 }, "definition_json": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "status" ], "additionalProperties": false, "$ref": "#/components/schemas/CreateWorkflowDefinition" } } } }, "responses": { "201": { "description": "Created workflow definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "listWorkflowDefinitions", "summary": "List workflow definitions", "tags": [ "Workflow Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "read" } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "active", "deprecated", "inactive", "archived" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "List of workflow definitions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorkflowsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/workflows/triggers": { "get": { "operationId": "listWorkflowsByTrigger", "summary": "List workflows matching trigger criteria", "tags": [ "Workflow Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "read" } ], "parameters": [ { "name": "entity_type_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "relationship_rule_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "entity_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "event_action", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workflow_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "trigger_definition_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "entity_payload", "in": "query", "required": false, "schema": { "type": "object", "additionalProperties": {}, "description": "Entity payload filter for trigger matching" } } ], "responses": { "200": { "description": "Workflows matching trigger criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorkflowsByTriggerResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/workflows/resolve/{idOrName}": { "get": { "operationId": "resolveWorkflowDefinition", "summary": "Resolve a workflow definition by ID or name", "tags": [ "Workflow Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "read" } ], "parameters": [ { "name": "idOrName", "in": "path", "required": true, "schema": { "type": "string", "description": "Workflow ID or name" }, "description": "Workflow ID or name" }, { "name": "by_id", "in": "query", "required": false, "schema": { "description": "If true, resolve by ID instead of name", "type": "boolean" }, "description": "If true, resolve by ID instead of name" } ], "responses": { "200": { "description": "Resolved workflow definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/workflows/{id}": { "get": { "operationId": "getWorkflowDefinition", "summary": "Get workflow definition by ID", "tags": [ "Workflow Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Definition ID" }, "description": "Workflow Definition ID" } ], "responses": { "200": { "description": "Workflow definition details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateWorkflowDefinition", "summary": "Update a workflow definition", "tags": [ "Workflow Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Definition ID" }, "description": "Workflow Definition ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" }, "source_yaml": { "type": "string", "minLength": 1 }, "definition_json": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated workflow definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/workflows/{id}/definition": { "get": { "operationId": "getWorkflowDefinitionJson", "summary": "Get the raw workflow definition JSON", "tags": [ "Workflow Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Definition ID" }, "description": "Workflow Definition ID" } ], "responses": { "200": { "description": "Workflow definition JSON object" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateWorkflowDefinitionJson", "summary": "Replace the workflow definition JSON", "tags": [ "Workflow Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Definition ID" }, "description": "Workflow Definition ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "responses": { "200": { "description": "Updated workflow definition JSON" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/workflows/{id}/shares": { "get": { "operationId": "listWorkflowSharingShares", "summary": "List shares for this resource (owner view)", "tags": [ "Workflow Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Shares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createWorkflowSharingShare", "summary": "Create a share for this resource", "tags": [ "Workflow Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShare" } } } }, "responses": { "201": { "description": "Share created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/workflows/{id}/shares/{shareId}": { "put": { "operationId": "updateWorkflowSharingShare", "summary": "Update a share", "tags": [ "Workflow Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShare" } } } }, "responses": { "200": { "description": "Share updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteWorkflowSharingShare", "summary": "Delete a share", "tags": [ "Workflow Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Share deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/workflows/{id}/grants": { "get": { "operationId": "listWorkflowSharingGrants", "summary": "List grants for this resource (owner view)", "tags": [ "Workflow Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Grants" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createWorkflowSharingGrant", "summary": "Create a grant for this resource", "tags": [ "Workflow Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResourceGrant" } } } }, "responses": { "201": { "description": "Grant created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/workflows/{id}/grants/{grantId}": { "put": { "operationId": "updateWorkflowSharingGrant", "summary": "Update a grant", "tags": [ "Workflow Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGrant" } } } }, "responses": { "200": { "description": "Grant updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteWorkflowSharingGrant", "summary": "Delete a grant", "tags": [ "Workflow Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Grant deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs": { "post": { "operationId": "createJobDefinition", "summary": "Create a new job definition", "tags": [ "Job Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Created job definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetJobResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "listJobDefinitions", "summary": "List job definitions", "tags": [ "Job Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "read" } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "status_in", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "name_version_in", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+@\\d+(\\.\\d+)?(\\.\\d+)?$" } } }, { "name": "id_in", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "List of job definitions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs/resolve": { "get": { "operationId": "resolveJobDefinitions", "summary": "Resolve multiple job definitions by name@version", "tags": [ "Job Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "read" } ], "parameters": [ { "name": "name_version_in", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated list of name@version pairs" }, "description": "Comma-separated list of name@version pairs" } ], "responses": { "200": { "description": "Resolved job definitions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveJobsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs/resolve-by-id": { "get": { "operationId": "resolveJobDefinitionsById", "summary": "Resolve multiple job definitions by ID", "tags": [ "Job Definitions" ], "security": [ { "BasicAuth": [] } ], "description": "The pinned-id counterpart to resolving by name@version — used when a workflow's job-step reference carries a `resolvedJobId` stamped at publish time.", "x-permission": [ { "resource": "job_definition", "action": "read" } ], "parameters": [ { "name": "id_in", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated list of job definition IDs" }, "description": "Comma-separated list of job definition IDs" } ], "responses": { "200": { "description": "Resolved job definitions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveJobsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs/resolve/{name}/{version}": { "get": { "operationId": "resolveJobDefinitionByName", "summary": "Resolve a job definition by name and optional version", "tags": [ "Job Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "read" } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "description": "Job definition name" }, "description": "Job definition name" }, { "name": "version", "in": "path", "required": true, "schema": { "description": "Semver version (optional, defaults to latest)", "type": "string" }, "description": "Semver version (optional, defaults to latest)" } ], "responses": { "200": { "description": "Resolved job definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveJobResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job definition not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs/{id}": { "get": { "operationId": "getJobDefinition", "summary": "Get job definition by ID", "tags": [ "Job Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Job Definition ID" }, "description": "Job Definition ID" } ], "responses": { "200": { "description": "Job definition details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetJobResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job definition not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateJobDefinition", "summary": "Update a job definition", "tags": [ "Job Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Job Definition ID" }, "description": "Job Definition ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" }, "source_yaml": { "type": "string", "minLength": 1 }, "definition_json": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated job definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetJobResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job definition not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs/{id}/definition": { "get": { "operationId": "getJobDefinitionJson", "summary": "Get the raw job definition JSON", "tags": [ "Job Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Job Definition ID" }, "description": "Job Definition ID" } ], "responses": { "200": { "description": "Job definition JSON object" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job definition not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateJobDefinitionJson", "summary": "Replace the job definition JSON", "tags": [ "Job Definitions" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Job Definition ID" }, "description": "Job Definition ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "responses": { "200": { "description": "Updated job definition JSON" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job definition not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs/{id}/shares": { "get": { "operationId": "listJobSharingShares", "summary": "List shares for this resource (owner view)", "tags": [ "Job Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Shares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createJobSharingShare", "summary": "Create a share for this resource", "tags": [ "Job Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShare" } } } }, "responses": { "201": { "description": "Share created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs/{id}/shares/{shareId}": { "put": { "operationId": "updateJobSharingShare", "summary": "Update a share", "tags": [ "Job Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShare" } } } }, "responses": { "200": { "description": "Share updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteJobSharingShare", "summary": "Delete a share", "tags": [ "Job Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Share deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs/{id}/grants": { "get": { "operationId": "listJobSharingGrants", "summary": "List grants for this resource (owner view)", "tags": [ "Job Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Grants" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createJobSharingGrant", "summary": "Create a grant for this resource", "tags": [ "Job Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResourceGrant" } } } }, "responses": { "201": { "description": "Grant created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/jobs/{id}/grants/{grantId}": { "put": { "operationId": "updateJobSharingGrant", "summary": "Update a grant", "tags": [ "Job Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGrant" } } } }, "responses": { "200": { "description": "Grant updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteJobSharingGrant", "summary": "Delete a grant", "tags": [ "Job Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_definition", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Grant deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/specs": { "post": { "operationId": "createAppSpec", "summary": "Create a new app spec", "tags": [ "App Specs" ], "security": [ { "BasicAuth": [] } ], "description": "`spec_document.widgets[*].config` follows the `WidgetConfig` component (discriminated by `widgetComponent`). Configs may carry `{{ }}` smart-values — see SMART-VALUES.md; the documented shape is the resolved one.", "x-permission": [ { "resource": "app_spec", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAppSpec" } } } }, "responses": { "201": { "description": "App spec created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An app spec with this name already exists" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "listAppSpecs", "summary": "List app specs", "tags": [ "App Specs" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "read" } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "active", "deprecated", "inactive", "archived" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "App specs" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/specs/{id}": { "get": { "operationId": "getAppSpec", "summary": "Fetch an app spec by id", "tags": [ "App Specs" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "App spec ID" }, "description": "App spec ID" } ], "responses": { "200": { "description": "App spec" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateAppSpec", "summary": "Update an app spec (fans spec.policy out to consumer tenants)", "tags": [ "App Specs" ], "security": [ { "BasicAuth": [] } ], "description": "`spec_document.widgets[*].config` follows the `WidgetConfig` component (discriminated by `widgetComponent`). Configs may carry `{{ }}` smart-values — see SMART-VALUES.md; the documented shape is the resolved one.", "x-permission": [ { "resource": "app_spec", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "App spec ID" }, "description": "App spec ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAppSpec" } } } }, "responses": { "200": { "description": "App spec updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/specs/{id}/shares": { "get": { "operationId": "listAppSpecSharingShares", "summary": "List shares for this resource (owner view)", "tags": [ "App Spec Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Shares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createAppSpecSharingShare", "summary": "Create a share for this resource", "tags": [ "App Spec Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShare" } } } }, "responses": { "201": { "description": "Share created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/specs/{id}/shares/{shareId}": { "put": { "operationId": "updateAppSpecSharingShare", "summary": "Update a share", "tags": [ "App Spec Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShare" } } } }, "responses": { "200": { "description": "Share updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteAppSpecSharingShare", "summary": "Delete a share", "tags": [ "App Spec Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Share deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/specs/{id}/grants": { "get": { "operationId": "listAppSpecSharingGrants", "summary": "List grants for this resource (owner view)", "tags": [ "App Spec Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Grants" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createAppSpecSharingGrant", "summary": "Create a grant for this resource", "tags": [ "App Spec Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResourceGrant" } } } }, "responses": { "201": { "description": "Grant created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/definition/specs/{id}/grants/{grantId}": { "put": { "operationId": "updateAppSpecSharingGrant", "summary": "Update a grant", "tags": [ "App Spec Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGrant" } } } }, "responses": { "200": { "description": "Grant updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteAppSpecSharingGrant", "summary": "Delete a grant", "tags": [ "App Spec Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Grant deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/schema/schemas": { "get": { "operationId": "listSchemas", "summary": "List JSON schema catalog items", "tags": [ "Schemas" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "read" } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "internal", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "active", "deprecated", "inactive", "archived" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "List of schema catalog items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSchemasResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createSchema", "summary": "Create a new JSON schema catalog item", "tags": [ "Schemas" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJsonSchemaCatalogItem" } } } }, "responses": { "201": { "description": "Created schema catalog item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchemaResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/schema/schemas/{id}": { "get": { "operationId": "getSchema", "summary": "Get a schema catalog item by ID or name", "tags": [ "Schemas" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Schema ID (UUID or internal name)" }, "description": "Schema ID (UUID or internal name)" } ], "responses": { "200": { "description": "Schema catalog item details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchemaResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Schema not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateSchema", "summary": "Update a schema catalog item", "tags": [ "Schemas" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Schema ID (UUID or internal name)" }, "description": "Schema ID (UUID or internal name)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJsonSchemaCatalogItem" } } } }, "responses": { "200": { "description": "Updated schema catalog item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchemaResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Schema not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/schema/schemas/{id}/definition": { "get": { "operationId": "getSchemaDefinition", "summary": "Get the raw JSON Schema definition object", "tags": [ "Schemas" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Schema ID (UUID or internal name)" }, "description": "Schema ID (UUID or internal name)" } ], "responses": { "200": { "description": "JSON Schema definition object" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Schema not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateSchemaDefinition", "summary": "Replace the JSON Schema definition", "tags": [ "Schemas" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Schema ID (UUID or internal name)" }, "description": "Schema ID (UUID or internal name)" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated JSON Schema definition" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Schema not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/schema/validate": { "post": { "operationId": "validateData", "summary": "Validate data against a JSON Schema", "tags": [ "Validation" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "read" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateSchemaDto" } } } }, "responses": { "200": { "description": "Validation result" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/schema/validate/bulk": { "post": { "operationId": "validateDataBulk", "summary": "Validate multiple data items against a JSON Schema", "tags": [ "Validation" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "read" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateSchemaBulkDto" } } } }, "responses": { "200": { "description": "Bulk validation results" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/schema/schemas/{id}/shares": { "get": { "operationId": "listSchemaSharingShares", "summary": "List shares for this resource (owner view)", "tags": [ "Schema Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Shares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createSchemaSharingShare", "summary": "Create a share for this resource", "tags": [ "Schema Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShare" } } } }, "responses": { "201": { "description": "Share created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/schema/schemas/{id}/shares/{shareId}": { "put": { "operationId": "updateSchemaSharingShare", "summary": "Update a share", "tags": [ "Schema Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShare" } } } }, "responses": { "200": { "description": "Share updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteSchemaSharingShare", "summary": "Delete a share", "tags": [ "Schema Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Share deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/schema/schemas/{id}/grants": { "get": { "operationId": "listSchemaSharingGrants", "summary": "List grants for this resource (owner view)", "tags": [ "Schema Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Grants" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createSchemaSharingGrant", "summary": "Create a grant for this resource", "tags": [ "Schema Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResourceGrant" } } } }, "responses": { "201": { "description": "Grant created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/schema/schemas/{id}/grants/{grantId}": { "put": { "operationId": "updateSchemaSharingGrant", "summary": "Update a grant", "tags": [ "Schema Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGrant" } } } }, "responses": { "200": { "description": "Grant updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteSchemaSharingGrant", "summary": "Delete a grant", "tags": [ "Schema Sharing" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "json_schema", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Grant deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/config": { "get": { "operationId": "getAppConfigForSpec", "summary": "Fetch this tenant's app_config for the spec", "tags": [ "Config" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_config", "action": "read" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "App config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAppConfigResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "App config does not exist for this spec" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "upsertAppConfigForSpec", "summary": "Upsert (create on first call, update afterwards) the tenant's app_config", "tags": [ "Config" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_config", "action": "update" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertAppConfig" } } } }, "responses": { "200": { "description": "App config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAppConfigResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteAppConfigForSpec", "summary": "Remove the activation for this spec", "tags": [ "Config" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_config", "action": "delete" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "App config deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/integrations": { "get": { "operationId": "listAppIntegrations", "summary": "List integrations under this app", "tags": [ "Integrations" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_integration", "action": "read" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "is_enabled", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "Integrations" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createAppIntegration", "summary": "Create an integration for an external company", "tags": [ "Integrations" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_integration", "action": "create" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAppIntegration" } } } }, "responses": { "201": { "description": "Integration created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "An integration for this `(spec, external_company)` pair already exists. The pair is unique per app — update the existing integration or delete it first." }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/integrations/{integrationId}": { "get": { "operationId": "getAppIntegration", "summary": "Read a single integration", "tags": [ "Integrations" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_integration", "action": "read" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Integration" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateAppIntegration", "summary": "Update name, config, allowed_origins, or is_enabled on an integration", "tags": [ "Integrations" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_integration", "action": "update" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "is_enabled": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": {} }, "allowed_origins": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(https?:\\/\\/)[A-Za-z0-9._\\-*]+(:\\d{1,5})?$" } } }, "additionalProperties": {} } } } }, "responses": { "200": { "description": "Integration updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Update would collide with another integration's uniqueness constraints on this app." }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteAppIntegration", "summary": "Remove an integration", "tags": [ "Integrations" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_integration", "action": "delete" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Integration deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/integrations/{integrationId}/token": { "put": { "operationId": "issueAppToken", "summary": "Rotate-on-issue: revoke any active token and mint a new one for the integration. The raw token is returned once.", "tags": [ "Tokens" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_token", "action": "update" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueAppToken" } } } }, "responses": { "200": { "description": "Token row plus the raw value (raw_token returned exactly once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueAppTokenResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/integrations/{integrationId}/tokens": { "get": { "operationId": "listAppTokens", "summary": "List active + revoked tokens for the integration (no raw values).", "tags": [ "Tokens" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_token", "action": "read" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAppTokensResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/integrations/{integrationId}/tokens/{tokenId}": { "delete": { "operationId": "revokeAppToken", "summary": "Explicitly revoke a single token. Rare — the PUT rotate path already revokes the prior active token.", "tags": [ "Tokens" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_token", "action": "delete" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Token revoked" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/principals": { "get": { "operationId": "listPrincipalConfigs", "summary": "List principal configs under this app", "tags": [ "Principals" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "principal_config", "action": "read" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "principal_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "team", "user" ] } }, { "name": "principal_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } } ], "responses": { "200": { "description": "Principal configs" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/principals/{type}/{principalId}": { "get": { "operationId": "getPrincipalConfig", "summary": "Read a principal config by natural key", "tags": [ "Principals" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "principal_config", "action": "read" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "company", "team", "user" ] } }, { "name": "principalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Principal config" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "upsertPrincipalConfig", "summary": "Upsert the config for one principal under this app", "tags": [ "Principals" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "principal_config", "action": "update" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "company", "team", "user" ] } }, { "name": "principalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertPrincipalConfig" } } } }, "responses": { "200": { "description": "Principal config" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deletePrincipalConfig", "summary": "Remove a principal override", "tags": [ "Principals" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "principal_config", "action": "delete" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "company", "team", "user" ] } }, { "name": "principalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Principal config deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/policies": { "get": { "operationId": "listSpecRoles", "summary": "List the spec-defined policy roles materialised in this tenant.", "tags": [ "App Roles" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "read" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Roles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSpecRolesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/{specId}/users/{authUserId}/policy": { "put": { "operationId": "assignSpecRole", "summary": "Assign a user to a spec-defined policy by key (e.g. {policy: \"editor\"}).", "tags": [ "App Roles" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "update" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "authUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignSpecPolicy" } } } }, "responses": { "200": { "description": "Assignment created/updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "App not activated for this tenant" }, "422": { "description": "Unknown policy key — not defined in spec_document.policies" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "unassignSpecRole", "summary": "Remove a user's spec-role assignment so resolve_user_app_policy falls back to the default.", "tags": [ "App Roles" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "delete" } ], "parameters": [ { "name": "specId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "authUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Assignment removed" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/apps/run": { "post": { "operationId": "runBridge", "summary": "Render a bridge dashboard for an external provider", "tags": [ "Run" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "app_spec", "action": "read" } ], "responses": { "200": { "description": "Bridge response (surfaces, state, referenceData)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Missing or invalid app context headers" }, "403": { "description": "Origin not in integration's allowed_origins, or app/integration disabled" }, "404": { "description": "App config / spec not found, or no dashboards" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/wr": { "post": { "operationId": "triggerWorkflow", "summary": "Trigger a workflow run", "tags": [ "Workflow Runs" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_run", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerWorkflow" } } } }, "responses": { "200": { "description": "Triggered workflow run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWorkflowRunResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/wr/{workflowRunId}/retry": { "post": { "operationId": "retryWorkflowRun", "summary": "Retry a failed workflow run", "tags": [ "Workflow Runs" ], "security": [ { "BasicAuth": [] } ], "description": "Creates a new workflow_run linked to the original via `original_workflow_run_id`, with `attempt_number` incremented. Only the latest attempt of a retry group can be retried.", "x-permission": [ { "resource": "workflow_run", "action": "update" } ], "parameters": [ { "name": "workflowRunId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Run ID (must be the latest attempt of its group)" }, "description": "Workflow Run ID (must be the latest attempt of its group)" } ], "responses": { "202": { "description": "Workflow run retry initiated (async dispatch)" }, "400": { "description": "The provided run is not the latest attempt of its retry group" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow run not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/wr/{workflowRunId}/cancel": { "post": { "operationId": "cancelWorkflowRun", "summary": "Cancel a running workflow", "tags": [ "Workflow Runs" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_run", "action": "update" } ], "parameters": [ { "name": "workflowRunId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Run ID" }, "description": "Workflow Run ID" } ], "responses": { "200": { "description": "Workflow run cancellation initiated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow run not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/runs/workflows": { "get": { "operationId": "listWorkflowRuns", "summary": "List workflow runs with filters", "tags": [ "Workflow Run Queries" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_run", "action": "read" } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, { "name": "workflow_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "workflow_name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "idempotency_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "event_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "entity_type_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "entity_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } } ], "responses": { "200": { "description": "List of workflow runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorkflowRunsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/runs/workflows/{id}": { "get": { "operationId": "getWorkflowRun", "summary": "Get a workflow run by ID with its job runs", "tags": [ "Workflow Run Queries" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_run", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Run ID" }, "description": "Workflow Run ID" }, { "name": "include_attempts", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow run details with job runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWorkflowRunResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow run not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/runs/jobs": { "get": { "operationId": "listJobRuns", "summary": "List job runs with filters", "tags": [ "Workflow Run Queries" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "job_run", "action": "read" } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, { "name": "workflow_run_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "job_run_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "step_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status_in", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } } ], "responses": { "200": { "description": "List of job runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobRunsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/runs/actions": { "get": { "operationId": "listActionRuns", "summary": "List action runs for a job run", "tags": [ "Workflow Run Queries" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "action_run", "action": "read" } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, { "name": "workflow_run_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "job_run_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "step_id_in_job", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status_in", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of action runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListActionRunsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/schedules": { "post": { "operationId": "createSchedule", "summary": "Create a cron schedule for a workflow trigger", "tags": [ "Schedules" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowScheduleDto" } } } }, "responses": { "200": { "description": "Created schedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "listSchedules", "summary": "List schedules for a workflow", "tags": [ "Schedules" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "read" } ], "parameters": [ { "name": "workflow_name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "List of schedules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSchedulesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteSchedule", "summary": "Delete a workflow schedule", "tags": [ "Schedules" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_definition", "action": "update" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWorkflowScheduleDto" } } } }, "responses": { "200": { "description": "Schedule deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/{id}/activate": { "post": { "operationId": "activateWorkflow", "summary": "Activate a workflow in the current tenant", "tags": [ "Workflow Activation" ], "security": [ { "BasicAuth": [] } ], "description": "Materialises the per-tenant activation of a workflow definition: tenant config, triggers (with webhook URLs + HMAC secrets minted inline), and the resolved policy binding. Sharee tenants activate their own instance; the owner cannot reach into another tenant's activation. Requires the `workflow_config` capability in the caller's own tenant plus a read-share (or ownership) of the definition.", "x-permission": [ { "resource": "workflow_config", "action": "create" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow ID" }, "description": "Workflow ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateWorkflow" } } } }, "responses": { "200": { "description": "Activated workflow with triggers and policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateWorkflowResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/{id}/config": { "put": { "operationId": "updateWorkflowConfig", "summary": "Update a workflow's tenant configuration", "tags": [ "Workflow Activation" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_config", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow ID" }, "description": "Workflow ID" } ], "requestBody": { "content": { "application/json": { "schema": { "default": { "env": {} }, "$ref": "#/components/schemas/WorkflowConfig" } } } }, "responses": { "200": { "description": "Updated workflow configuration" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/{id}/triggers": { "get": { "operationId": "listWorkflowTriggers", "summary": "List a workflow's triggers", "tags": [ "Workflow Activation" ], "security": [ { "BasicAuth": [] } ], "description": "Returns the activated triggers for the workflow, including webhook URLs, cron schedules, secret presence, and config status.", "x-permission": [ { "resource": "workflow_config", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow ID" }, "description": "Workflow ID" } ], "responses": { "200": { "description": "List of workflow triggers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWorkflowTriggersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/{id}/triggers/{triggerId}/secret": { "post": { "operationId": "generateWorkflowTriggerSecret", "summary": "Mint or rotate a webhook secret for a trigger", "tags": [ "Workflow Activation" ], "security": [ { "BasicAuth": [] } ], "description": "Generates (or rotates) the HMAC webhook secret for a trigger. The plaintext secret is returned ONCE and cannot be retrieved again.", "x-permission": [ { "resource": "workflow_config", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow ID" }, "description": "Workflow ID" }, { "name": "triggerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Trigger ID" }, "description": "Workflow Trigger ID" } ], "responses": { "201": { "description": "Generated webhook secret (plaintext returned once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateWebhookSecretResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow or trigger not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "revokeWorkflowTriggerSecret", "summary": "Revoke a trigger's webhook secret", "tags": [ "Workflow Activation" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "workflow_config", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow ID" }, "description": "Workflow ID" }, { "name": "triggerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Trigger ID" }, "description": "Workflow Trigger ID" } ], "responses": { "200": { "description": "Webhook secret revoked" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow or trigger not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/{id}/triggers/{triggerId}/enable": { "put": { "operationId": "enableWorkflowTrigger", "summary": "Re-enable a paused trigger", "tags": [ "Workflow Activation" ], "security": [ { "BasicAuth": [] } ], "description": "Resumes a paused trigger. For cron triggers, recreates the QStash schedule.", "x-permission": [ { "resource": "workflow_config", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow ID" }, "description": "Workflow ID" }, { "name": "triggerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Trigger ID" }, "description": "Workflow Trigger ID" } ], "responses": { "200": { "description": "Trigger enabled" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow or trigger not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/workflows/{id}/triggers/{triggerId}/disable": { "put": { "operationId": "disableWorkflowTrigger", "summary": "Pause a trigger", "tags": [ "Workflow Activation" ], "security": [ { "BasicAuth": [] } ], "description": "Pauses a trigger. For cron triggers, deletes the QStash schedule. The trigger row is preserved so re-enabling is fast.", "x-permission": [ { "resource": "workflow_config", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow ID" }, "description": "Workflow ID" }, { "name": "triggerId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Workflow Trigger ID" }, "description": "Workflow Trigger ID" } ], "responses": { "200": { "description": "Trigger disabled" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Workflow or trigger not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/users": { "get": { "operationId": "listAccessUsers", "summary": "List user_profile rows in the caller's tenant", "tags": [ "Users" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "user", "action": "read" } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Tenant directory" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createAccessUser", "summary": "Provision an auth user + user_profile + optional role bindings in the caller's tenant", "tags": [ "Users" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "user", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessUser" } } } }, "responses": { "201": { "description": "User created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "User already exists in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/users/{authUserId}": { "patch": { "operationId": "updateAccessUser", "summary": "Update profile fields of a user in the caller's tenant", "tags": [ "Users" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "user", "action": "update" } ], "parameters": [ { "name": "authUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccessUser" } } } }, "responses": { "200": { "description": "Profile updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "User not found in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deactivateAccessUser", "summary": "Soft-deactivate a user_profile in this tenant (sets is_active_in_tenant=false). Does NOT delete the auth.users row.", "tags": [ "Users" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "user", "action": "delete" } ], "parameters": [ { "name": "authUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "User deactivated in this tenant" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "User not found in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/roles": { "get": { "operationId": "listAccessRoles", "summary": "List system + tenant roles visible to the caller", "tags": [ "Roles" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "role", "action": "read" } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "description": "Exact-match role name filter (e.g. `tenant_admin`).", "type": "string" }, "description": "Exact-match role name filter (e.g. `tenant_admin`)." } ], "responses": { "200": { "description": "Roles" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/role-assignments": { "get": { "operationId": "listRoleAssignments", "summary": "List role assignments in this tenant (optionally filtered)", "tags": [ "Role Assignments" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "auth_user_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "policy_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "role_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Assignments" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createRoleAssignment", "summary": "Bind a user to a role or policy in this tenant", "tags": [ "Role Assignments" ], "security": [ { "BasicAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleAssignment" } } } }, "responses": { "201": { "description": "Assignment created" }, "400": { "description": "Already exists" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/role-assignments/{authUserId}/{roleId}": { "delete": { "operationId": "deleteRoleAssignment", "summary": "Revoke a role assignment", "tags": [ "Role Assignments" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "authUserId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Assignment removed" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/policies": { "get": { "operationId": "listPolicies", "summary": "List policies in this tenant", "tags": [ "Policies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "access_policy", "action": "read" } ], "responses": { "200": { "description": "Policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPoliciesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createPolicy", "summary": "Create a policy, optionally with an initial grant set", "tags": [ "Policies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "access_policy", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicy" } } } }, "responses": { "201": { "description": "Policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "A policy with this name already exists" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/policies/{id}": { "get": { "operationId": "getPolicy", "summary": "Fetch a policy with its grants", "tags": [ "Policies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "access_policy", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Policy ID (access_policy.id)" }, "description": "Policy ID (access_policy.id)" } ], "responses": { "200": { "description": "Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "operationId": "updatePolicy", "summary": "Update a policy's metadata (name, description)", "tags": [ "Policies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "access_policy", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Policy ID (access_policy.id)" }, "description": "Policy ID (access_policy.id)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePolicy" } } } }, "responses": { "200": { "description": "Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "A policy with this name already exists" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deletePolicy", "summary": "Delete a policy. Cascades grants via cascade_delete_policy_grants", "tags": [ "Policies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "access_policy", "action": "delete" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Policy ID (access_policy.id)" }, "description": "Policy ID (access_policy.id)" } ], "responses": { "200": { "description": "Policy deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/policies/{id}/grants": { "get": { "operationId": "listPolicyGrants", "summary": "List the grants attached to a policy", "tags": [ "Policies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "access_policy", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Policy ID (access_policy.id)" }, "description": "Policy ID (access_policy.id)" } ], "responses": { "200": { "description": "Policy grants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPolicyGrantsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "addPolicyGrants", "summary": "Append grants to a policy", "tags": [ "Policies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "access_policy", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Policy ID (access_policy.id)" }, "description": "Policy ID (access_policy.id)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPolicyGrants" } } } }, "responses": { "201": { "description": "Grants added (plain list, or partial result with no rejections when partial_success: true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPolicyGrantsResponse" } } } }, "207": { "description": "partial_success: true and at least one grant was rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartialGrantResultResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "replacePolicyGrants", "summary": "Replace a policy's full grant set (destructive)", "tags": [ "Policies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "access_policy", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Policy ID (access_policy.id)" }, "description": "Policy ID (access_policy.id)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplacePolicyGrants" } } } }, "responses": { "200": { "description": "Grants replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPolicyGrantsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/policies/{id}/grants/{grantId}": { "delete": { "operationId": "deletePolicyGrant", "summary": "Remove a single grant from a policy", "tags": [ "Policies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "access_policy", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Policy ID" }, "description": "Policy ID" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Grant ID" }, "description": "Grant ID" } ], "responses": { "200": { "description": "Grant deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/grants": { "get": { "operationId": "listAccessGrants", "summary": "List intra-tenant resource_access_grant rows", "tags": [ "Grants" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "resource_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resource_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "grantee_kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user", "team", "policy" ] } }, { "name": "grantee_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } } ], "responses": { "200": { "description": "Grants" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createAccessGrant", "summary": "Create a grant (tenant_id pinned from auth context)", "tags": [ "Grants" ], "security": [ { "BasicAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGrant" } } } }, "responses": { "201": { "description": "Grant created" }, "400": { "description": "Validation error (e.g. cross-tenant)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/grants/{id}": { "put": { "operationId": "updateAccessGrant", "summary": "Update a grant's actions or is_active", "tags": [ "Grants" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGrant" } } } }, "responses": { "200": { "description": "Grant updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteAccessGrant", "summary": "Delete a grant", "tags": [ "Grants" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "Grant deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/shares": { "get": { "operationId": "listAccessShares", "summary": "List inbound + outbound resource_share rows for this tenant", "tags": [ "Shares" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "default": "all", "type": "string", "enum": [ "outbound", "inbound", "all" ] } } ], "responses": { "200": { "description": "Shares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/external-users": { "get": { "operationId": "listAccessExternalUsers", "summary": "List external_users in this tenant", "tags": [ "External Users" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "external_user", "action": "read" } ], "parameters": [ { "name": "external_company_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "External users" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createAccessExternalUser", "summary": "Pre-provision an external_user (tenant_id pinned from auth context)", "tags": [ "External Users" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "external_user", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantCreateExternalUser" } } } }, "responses": { "200": { "description": "Idempotent no-op or linked existing email — outcome in response body" }, "201": { "description": "External user created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Email already bound to a different external_user in this tenant — pass link_existing_email=true to override" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/external-users/{id}": { "get": { "operationId": "getAccessExternalUser", "summary": "Get a single external_user in this tenant", "tags": [ "External Users" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "external_user", "action": "read" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "External user" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateAccessExternalUser", "summary": "Update external_data or is_active (busts bridge runtime cache)", "tags": [ "External Users" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "external_user", "action": "update" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUpdateExternalUser" } } } }, "responses": { "200": { "description": "External user updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deactivateAccessExternalUser", "summary": "Soft-deactivate (is_active=false). Hard delete is intentionally not supported — the auto-create flow would happily recreate the row on next login.", "tags": [ "External Users" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "external_user", "action": "delete" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "description": "UUID format (PostgreSQL compatible)" } ], "responses": { "200": { "description": "External user deactivated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/external-companies": { "get": { "operationId": "listAccessExternalCompanies", "summary": "List external_company rows in this tenant", "tags": [ "External Companies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "external_company", "action": "read" } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "External companies (paginated)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/external-companies/{companyId}": { "get": { "operationId": "getAccessExternalCompany", "summary": "Get a single external_company in this tenant", "tags": [ "External Companies" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "external_company", "action": "read" } ], "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "external_company ID" }, "description": "external_company ID" } ], "responses": { "200": { "description": "External company" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Not found in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/api-tokens": { "post": { "operationId": "createAccessApiToken", "summary": "Mint an api_token in the caller's tenant", "tags": [ "API Tokens" ], "security": [ { "BasicAuth": [] } ], "description": "Mint a tenant-scoped api_token. When `policy_id` is supplied the token runs in policy mode; when omitted it mints in role mode (PAT semantic). The plaintext token is returned ONCE in the create response and cannot be retrieved later.", "x-permission": [ { "resource": "api_token", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessApiToken" } } } }, "responses": { "201": { "description": "Token minted (plaintext returned once)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "listAccessApiTokens", "summary": "List api_tokens in the caller's tenant", "tags": [ "API Tokens" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "api_token", "action": "read" } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "revoked", "expired" ] } } ], "responses": { "200": { "description": "Tokens (metadata only, never the secret)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/api-tokens/{tokenId}": { "delete": { "operationId": "revokeAccessApiToken", "summary": "Revoke (soft-deactivate) an api_token", "tags": [ "API Tokens" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "api_token", "action": "delete" } ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "API token ID" }, "description": "API token ID" } ], "responses": { "204": { "description": "Token revoked" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Token not found in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/api-tokens/{tokenId}/policy": { "put": { "operationId": "setAccessApiTokenPolicy", "summary": "Attach / re-target the token's policy", "tags": [ "API Tokens" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "api_token", "action": "update" } ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "API token ID" }, "description": "API token ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutApiTokenPolicy" } } } }, "responses": { "200": { "description": "Token policy updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Token or policy not found in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "clearAccessApiTokenPolicy", "summary": "Detach the token's policy (revert to role mode)", "tags": [ "API Tokens" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "api_token", "action": "update" } ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "API token ID" }, "description": "API token ID" } ], "responses": { "200": { "description": "Token policy cleared" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Token not found in this tenant" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/manifests": { "get": { "operationId": "listManifests", "summary": "List policy manifests owned by this tenant", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "direction", "in": "query", "required": false, "schema": { "default": "outbound", "type": "string", "enum": [ "outbound", "incoming" ] } } ], "responses": { "200": { "description": "Manifests" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createManifest", "summary": "Create a policy manifest (owner = caller's tenant)", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManifest" } } } }, "responses": { "201": { "description": "Manifest created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "A manifest with this name already exists" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/manifests/{manifestId}": { "get": { "operationId": "getManifest", "summary": "Get a manifest", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" } ], "responses": { "200": { "description": "Manifest" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Manifest not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "operationId": "updateManifest", "summary": "Update a manifest's metadata", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateManifest" } } } }, "responses": { "200": { "description": "Manifest updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Manifest not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteManifest", "summary": "Delete a manifest", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" } ], "responses": { "200": { "description": "Manifest deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Manifest not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/manifests/{manifestId}/materialised-shares": { "get": { "operationId": "listManifestMaterialisedShares", "summary": "List the concrete resource_share rows materialised from this manifest", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Materialised shares" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/manifests/{manifestId}/publications": { "get": { "operationId": "listManifestPublications", "summary": "List a manifest's publications to grantee tenants", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Publications" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createManifestPublication", "summary": "Publish a manifest to a grantee tenant", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublication" } } } }, "responses": { "200": { "description": "Publication already existed (idempotent)" }, "201": { "description": "Publication created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/manifests/{manifestId}/publications/{publicationId}": { "patch": { "operationId": "updateManifestPublication", "summary": "Update a manifest publication", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" }, { "name": "publicationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Publication ID" }, "description": "Publication ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePublication" } } } }, "responses": { "200": { "description": "Publication updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Publication not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteManifestPublication", "summary": "Delete a manifest publication", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" }, { "name": "publicationId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Publication ID" }, "description": "Publication ID" } ], "responses": { "200": { "description": "Publication deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Publication not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/manifests/{manifestId}/subscriptions": { "get": { "operationId": "getManifestSubscription", "summary": "Get the caller tenant's subscription to a manifest", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" } ], "responses": { "200": { "description": "Subscription (null if none)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createManifestSubscription", "summary": "Subscribe the caller's tenant to a manifest publication", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" } ], "responses": { "201": { "description": "Subscription created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteManifestSubscription", "summary": "Unsubscribe the caller's tenant from a manifest publication", "tags": [ "Manifests" ], "security": [ { "BasicAuth": [] } ], "parameters": [ { "name": "manifestId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Manifest ID" }, "description": "Manifest ID" } ], "responses": { "200": { "description": "Subscription removed" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/secrets": { "post": { "operationId": "createSecret", "summary": "Create or set a scoped secret (defaults to tenant scope)", "tags": [ "Secrets" ], "security": [ { "BasicAuth": [] } ], "description": "Manages scoped secret values. `scope` defaults to `tenant` (resolved at runtime as `{{ secrets.tenant. }}`); pass `scope` + `scopeId` to target `user` / `company` / `team` / `app`. The value is stored in Supabase Vault. Authorization is enforced by the database (per-scope free-pass / `secret` grant); a tenant admin may write any scope. End users also provision their own user/app secrets from inside a running app via the `setSecret` step. See `docs/guides/SECRETS-HOWTO.md`. Set semantics (upsert): re-posting an existing name overwrites its value and returns the SAME 201 shape as a fresh create, so a create-only token cannot enumerate names via the response.", "x-permission": [ { "resource": "secret", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSecretRequest" } } } }, "responses": { "201": { "description": "Secret created or updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "operationId": "updateSecret", "summary": "Update (upsert) a scoped secret (defaults to tenant scope)", "tags": [ "Secrets" ], "security": [ { "BasicAuth": [] } ], "description": "Manages scoped secret values. `scope` defaults to `tenant` (resolved at runtime as `{{ secrets.tenant. }}`); pass `scope` + `scopeId` to target `user` / `company` / `team` / `app`. The value is stored in Supabase Vault. Authorization is enforced by the database (per-scope free-pass / `secret` grant); a tenant admin may write any scope. End users also provision their own user/app secrets from inside a running app via the `setSecret` step. See `docs/guides/SECRETS-HOWTO.md`. Upsert: rotates the stored value (the old value is overwritten in vault and cannot be recovered), creating it if absent — PUT shares set semantics with POST.", "x-permission": [ { "resource": "secret", "action": "update" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSecretRequest" } } } }, "responses": { "200": { "description": "Secret created or updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "listSecrets", "summary": "List secret metadata visible to the caller (values not returned)", "tags": [ "Secrets" ], "security": [ { "BasicAuth": [] } ], "description": "Manages scoped secret values. `scope` defaults to `tenant` (resolved at runtime as `{{ secrets.tenant. }}`); pass `scope` + `scopeId` to target `user` / `company` / `team` / `app`. The value is stored in Supabase Vault. Authorization is enforced by the database (per-scope free-pass / `secret` grant); a tenant admin may write any scope. End users also provision their own user/app secrets from inside a running app via the `setSecret` step. See `docs/guides/SECRETS-HOWTO.md`. Returns `{ scope, name }` entries for the secrets the caller can see (their tenant, plus their own user/company/team/app memberships); decrypted values are never returned from any user-facing API. Pass `?scope=` to filter to a single scope.", "x-permission": [ { "resource": "secret", "action": "read" } ], "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tenant", "company", "team", "user", "app" ] } } ], "responses": { "200": { "description": "Wrapped list response: `{ data: SecretMetadata[] }`. Pagination is not applied — tenants typically hold a small fixed number of tenant-scope secrets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSecretsResponseEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/secrets/{name}": { "delete": { "operationId": "deleteSecret", "summary": "Delete a scoped secret (defaults to tenant scope)", "tags": [ "Secrets" ], "security": [ { "BasicAuth": [] } ], "description": "Manages scoped secret values. `scope` defaults to `tenant` (resolved at runtime as `{{ secrets.tenant. }}`); pass `scope` + `scopeId` to target `user` / `company` / `team` / `app`. The value is stored in Supabase Vault. Authorization is enforced by the database (per-scope free-pass / `secret` grant); a tenant admin may write any scope. End users also provision their own user/app secrets from inside a running app via the `setSecret` step. See `docs/guides/SECRETS-HOWTO.md`. Returns 404 if the secret never existed (matches an unknown name and a cross-tenant probe identically — no enumeration oracle).", "x-permission": [ { "resource": "secret", "action": "delete" } ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Secret deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Secret does not exist" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/access/me/permissions": { "get": { "operationId": "getMyPermissions", "summary": "Advisory permission snapshot for the current caller", "tags": [ "Me" ], "security": [ { "BasicAuth": [] } ], "description": "Returns the (resource, action) pairs the authenticated caller can likely perform, plus `is_super_admin` / `is_tenant_admin`. Advisory only — the docs portal uses it to filter which operations to show; RLS / has_permission remain the server-side enforcement. No admin gate: any signed-in caller reads their own snapshot.", "responses": { "200": { "description": "The caller's effective permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectivePermissions" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/auth/token": { "post": { "operationId": "exchangeToken", "summary": "Exchange API credentials for a JWT", "tags": [ "Authentication" ], "security": [], "description": "Supports both JSON and form-encoded bodies, as well as HTTP Basic Auth.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchange" } } } }, "responses": { "200": { "description": "JWT access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchangeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "description": "Too many failed attempts" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/auth/tokens/api": { "post": { "operationId": "createApiToken", "summary": "Create a new API token", "tags": [ "Token Management" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "api_token", "action": "create" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiToken" } } } }, "responses": { "201": { "description": "Created API token with secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiTokenResponseEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "operationId": "listApiTokens", "summary": "List API tokens for the current tenant", "tags": [ "Token Management" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "api_token", "action": "read" } ], "responses": { "200": { "description": "List of API tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiTokensResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/auth/tokens/api/{tokenId}": { "delete": { "operationId": "revokeApiToken", "summary": "Revoke an API token", "tags": [ "Token Management" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "api_token", "action": "delete" } ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "API Token ID" }, "description": "API Token ID" } ], "responses": { "200": { "description": "Token revoked" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Token not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/auth/tokens/api/{tokenId}/usage": { "get": { "operationId": "getTokenUsageStats", "summary": "Get usage statistics for an API token", "tags": [ "Token Management" ], "security": [ { "BasicAuth": [] } ], "x-permission": [ { "resource": "api_token", "action": "read" } ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "API Token ID" }, "description": "API Token ID" }, { "name": "days", "in": "query", "required": false, "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 365 } } ], "responses": { "200": { "description": "Token usage statistics" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Token not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "schemas": { "ErrorObject": { "type": "object", "properties": { "status": { "description": "Mirrors the HTTP status code (informational only). SDK / frontend code MUST rely on the HTTP status, not parse this field.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "description": "Machine-readable, SDK-stable error code (e.g. ENTITY_NOT_FOUND, CARDINALITY_VIOLATED). See docs/guides/API-CONVENTIONS.md.", "type": "string" }, "message": { "type": "string", "description": "Human-readable error description" }, "name": { "description": "The underlying thrown error's constructor name (e.g. \"Error\", \"NotFoundError\") — set on run-persisted errors, absent on API error responses.", "type": "string" }, "action_details": { "description": "Which action/step within the run raised this error — set on workflow/job run errors, absent on API error responses.", "type": "object", "properties": { "action_run_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "step_id_in_job": { "type": "string" }, "action_name": { "type": "string" } }, "required": [ "action_run_id", "step_id_in_job", "action_name" ], "additionalProperties": false }, "details": { "description": "Additional error context. Shape varies per `code` (validation errors include the JSON path + Zod issues; not-found errors include the lookup key; conflict errors include the conflicting resource id).", "type": "object", "additionalProperties": {} } }, "required": [ "message" ], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorObject" } }, "required": [ "error" ], "additionalProperties": false }, "Entity": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "identifier_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attributes": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Entity attributes defined by the entity type schema" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "attributes_schema_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] } }, "required": [ "id", "name", "attributes_schema_id" ], "additionalProperties": false }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "relationship": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "required": [ "id" ], "additionalProperties": false }, "rule": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "entity": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "identifier_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attributes": { "type": "object", "additionalProperties": {}, "description": "Entity attributes defined by the entity type schema" } }, "required": [ "id", "type", "name", "identifier_key", "attributes" ], "additionalProperties": false }, "direction": { "type": "string", "enum": [ "from", "to" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "relationship", "rule", "entity", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": [ "id", "name", "identifier_key", "attributes", "created_at", "updated_at", "type" ], "additionalProperties": false }, "ListEntitiesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } }, "required": [ "data" ], "additionalProperties": false }, "CreateEntity": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "entity_type_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "attributes": { "type": "object", "additionalProperties": {}, "description": "Entity attributes defined by the entity type schema" } }, "required": [ "entity_type_id" ], "additionalProperties": false }, "GetEntityResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Entity" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateEntity": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "attributes": { "type": "object", "additionalProperties": {}, "description": "Entity attributes defined by the entity type schema" }, "merge_on_conflict": { "type": "boolean" }, "merge_cardinality": { "type": "string", "enum": [ "raise", "trim" ] } }, "required": [ "attributes" ], "additionalProperties": false }, "PatchEntityAttributes": { "type": "object", "additionalProperties": {}, "description": "Entity attributes defined by the entity type schema" }, "DeleteEntityResult": { "type": "object", "properties": { "entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "entity_type_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deleted_relationship_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deleted_artifact_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "entity_id", "entity_type_id", "entity_name", "deleted_relationship_count", "deleted_artifact_count" ], "additionalProperties": false }, "DeleteEntityResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteEntityResult" } }, "required": [ "data" ], "additionalProperties": false }, "UpsertEntities": { "type": "object", "properties": { "entity_type_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "entity_type_name": { "type": "string" }, "data": { "maxItems": 100000, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "attributes": { "type": "object", "additionalProperties": {}, "description": "Entity attributes defined by the entity type schema" }, "expected_updated_at": { "description": "Optimistic-concurrency token: the updated_at the caller last read for this row. When set and the row exists, a mismatch raises a 409 (CONCURRENT_MODIFICATION) instead of overwriting a concurrent change. Ignored for rows that resolve to a create.", "type": "string" }, "relationships": { "description": "Relationships to create after entity upsert. Target entities can be specified by ID (target_entity_id) or resolved by identifier_key lookup (target_identifier + target_type_name).", "type": "array", "items": { "type": "object", "properties": { "rule_name": { "type": "string", "minLength": 1 }, "target_entity_id": { "description": "Direct UUID of the target entity. Use this when you already know the entity ID.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "target_identifier": { "description": "Key-value pairs matching the target entity type's identifier_key attributes. For single-attribute keys: {\"port_code\": \"BEANR\"}. For multi-attribute keys: {\"imo_number\": \"1234567\", \"name\": \"Pacific Explorer\"}.", "type": "object", "additionalProperties": {} }, "target_type_name": { "description": "Entity type name of the target entity. Required when using target_identifier, optional with target_entity_id.", "type": "string", "minLength": 1 }, "direction": { "default": "from", "description": "Direction of the relationship: 'from' means this entity is the source, 'to' means this entity is the target", "type": "string", "enum": [ "from", "to" ] }, "attributes": { "description": "Optional relationship instance attributes", "type": "object", "additionalProperties": {} } }, "required": [ "rule_name", "direction" ], "additionalProperties": false } } }, "additionalProperties": false } }, "on_conflict": { "default": "replace", "type": "string", "enum": [ "raise", "ignore", "merge", "replace" ] }, "merge_on_conflict": { "type": "boolean" }, "merge_cardinality": { "type": "string", "enum": [ "raise", "trim" ] }, "suppress_events": { "default": false, "type": "boolean" }, "skip_unresolved_relationships": { "default": false, "description": "When true, an inline relationship whose `target_identifier` doesn't resolve to an existing entity is SKIPPED (and logged) instead of failing the whole upsert. Default false preserves the strict \"missing parent errors\" behaviour. Useful when syncing source data where child rows can legitimately reference parents outside the current batch/report.", "type": "boolean" } }, "required": [ "data", "on_conflict", "suppress_events", "skip_unresolved_relationships" ], "additionalProperties": false }, "EntityWithOperation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "identifier_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attributes": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Entity attributes defined by the entity type schema" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "attributes_schema_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] } }, "required": [ "id", "name", "attributes_schema_id" ], "additionalProperties": false }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "relationship": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "required": [ "id" ], "additionalProperties": false }, "rule": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "entity": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "identifier_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attributes": { "type": "object", "additionalProperties": {}, "description": "Entity attributes defined by the entity type schema" } }, "required": [ "id", "type", "name", "identifier_key", "attributes" ], "additionalProperties": false }, "direction": { "type": "string", "enum": [ "from", "to" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "relationship", "rule", "entity", "created_at", "updated_at" ], "additionalProperties": false } }, "operation_type": { "type": "string", "enum": [ "created", "updated", "ignored" ] } }, "required": [ "id", "name", "identifier_key", "attributes", "created_at", "updated_at", "type" ], "additionalProperties": false }, "UpsertBatchError": { "type": "object", "properties": { "batch_start": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "batch_end": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "batch_start", "batch_end", "error" ], "additionalProperties": false }, "UpsertEntitiesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityWithOperation" } }, "relationships_created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/UpsertBatchError" } } }, "required": [ "data" ], "additionalProperties": false }, "BulkDeleteEntities": { "type": "object", "properties": { "entity_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "suppress_events": { "default": true, "type": "boolean" } }, "required": [ "entity_ids", "suppress_events" ], "additionalProperties": false }, "BulkDeleteEntitiesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeleteEntityResult" } } }, "required": [ "data" ], "additionalProperties": false }, "BulkImportCsvResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total_rows": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updated_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ignored_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unchanged_count": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "relationships_created": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total_rows", "created_count", "updated_count", "ignored_count", "unchanged_count", "relationships_created" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "ParticleFilter": { "anyOf": [ { "$ref": "#/components/schemas/EqualsFilter" }, { "$ref": "#/components/schemas/IsFilter" }, { "$ref": "#/components/schemas/ComparisonFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/ContainsFilter" }, { "$ref": "#/components/schemas/OverlapsFilter" }, { "$ref": "#/components/schemas/LikeFilter" }, { "$ref": "#/components/schemas/SegmentFilter" }, { "$ref": "#/components/schemas/FuzzyFilter" }, { "$ref": "#/components/schemas/ExistsFilter" }, { "$ref": "#/components/schemas/RelExistsFilter" } ], "description": "A single field-level filter. Choose the operator based on your use case: eq/neq for exact match, gt/gte/lt/lte for ranges, in for set membership, like/ilike for patterns, cs for array-contains-all, ov for array-contains-any, segment for pipe-delimited fields, fuzzy for typo-tolerant text search, is for null/boolean checks, exists for relationship existence, rel_exists for conjoint-row predicates on a related entity." }, "EqualsFilter": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "eq", "neq" ], "description": "\"eq\" for exact match, \"neq\" for not-equal. Case-sensitive for text values." }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to filter on. Single element for entity-level fields: [\"name\"], [\"id\"], [\"created_at\"], [\"updated_at\"]. Two elements for indexed attributes: [\"attributes\", \"status\"]. Relationship fields are keyed by the RELATED ENTITY TYPE NAME (not the rule name), in EITHER direction (the engine resolves the connecting rule from→to or to→from): [\"relationships\", \"\", \"attributes\", \"field\"]. (Rule-name filtering uses the special form [\"relationships\", \"rule\", \"name\"].)" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "Value to compare against. Supports string, number, boolean, or null. Text comparison is case-sensitive; use ilike for case-insensitive matching." } }, "required": [ "operator", "path", "value" ], "additionalProperties": false, "description": "Exact equality or inequality filter. Compares the field value directly against the provided value." }, "IsFilter": { "type": "object", "properties": { "operator": { "type": "string", "const": "is", "description": "Must be \"is\"" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to filter on. Single element for entity-level fields: [\"name\"], [\"id\"], [\"created_at\"], [\"updated_at\"]. Two elements for indexed attributes: [\"attributes\", \"status\"]. Relationship fields are keyed by the RELATED ENTITY TYPE NAME (not the rule name), in EITHER direction (the engine resolves the connecting rule from→to or to→from): [\"relationships\", \"\", \"attributes\", \"field\"]. (Rule-name filtering uses the special form [\"relationships\", \"rule\", \"name\"].)" }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "true, false, or null. Use null to find entities where the attribute is unset. Use true/false for boolean attribute checks (IS TRUE / IS FALSE)." } }, "required": [ "operator", "path", "value" ], "additionalProperties": false, "description": "IS filter for null checks and boolean tests. `{\"operator\": \"is\", \"path\": [\"attributes\", \"verified\"], \"value\": null}` finds entities where verified is not set. `{\"operator\": \"is\", \"path\": [\"attributes\", \"active\"], \"value\": true}` finds entities where active IS TRUE." }, "ComparisonFilter": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "gt", "gte", "lt", "lte" ], "description": "\"gt\" (>), \"gte\" (>=), \"lt\" (<), \"lte\" (<=). Works with numbers, dates (ISO 8601 strings), and text." }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to filter on. Single element for entity-level fields: [\"name\"], [\"id\"], [\"created_at\"], [\"updated_at\"]. Two elements for indexed attributes: [\"attributes\", \"status\"]. Relationship fields are keyed by the RELATED ENTITY TYPE NAME (not the rule name), in EITHER direction (the engine resolves the connecting rule from→to or to→from): [\"relationships\", \"\", \"attributes\", \"field\"]. (Rule-name filtering uses the special form [\"relationships\", \"rule\", \"name\"].)" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Comparison value. For dates, use ISO 8601 format (e.g. \"2024-01-15T00:00:00Z\"). For numbers, use numeric values. Text uses lexicographic comparison." } }, "required": [ "operator", "path", "value" ], "additionalProperties": false, "description": "Range comparison filter. Useful for date ranges, numeric thresholds, and alphabetical ordering. Example: find entities created after a date with `{\"operator\": \"gte\", \"path\": [\"created_at\"], \"value\": \"2024-01-01T00:00:00Z\"}`." }, "InFilter": { "type": "object", "properties": { "operator": { "type": "string", "const": "in", "description": "Must be \"in\"" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to filter on. Single element for entity-level fields: [\"name\"], [\"id\"], [\"created_at\"], [\"updated_at\"]. Two elements for indexed attributes: [\"attributes\", \"status\"]. Relationship fields are keyed by the RELATED ENTITY TYPE NAME (not the rule name), in EITHER direction (the engine resolves the connecting rule from→to or to→from): [\"relationships\", \"\", \"attributes\", \"field\"]. (Rule-name filtering uses the special form [\"relationships\", \"rule\", \"name\"].)" }, "value": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "number" } } ], "description": "Array of values to match against. The field must exactly equal one of these values. All elements must be the same type (all strings or all numbers)." } }, "required": [ "operator", "path", "value" ], "additionalProperties": false, "description": "Array membership filter, matching entities where the field value is one of the provided values. Example: find entities with status active or pending with `{\"operator\": \"in\", \"path\": [\"attributes\", \"status\"], \"value\": [\"active\", \"pending\"]}`." }, "ContainsFilter": { "type": "object", "properties": { "operator": { "type": "string", "const": "cs", "description": "Must be \"cs\"" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to filter on. Single element for entity-level fields: [\"name\"], [\"id\"], [\"created_at\"], [\"updated_at\"]. Two elements for indexed attributes: [\"attributes\", \"status\"]. Relationship fields are keyed by the RELATED ENTITY TYPE NAME (not the rule name), in EITHER direction (the engine resolves the connecting rule from→to or to→from): [\"relationships\", \"\", \"attributes\", \"field\"]. (Rule-name filtering uses the special form [\"relationships\", \"rule\", \"name\"].)" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Value(s) that must ALL be present in the array field. A scalar value is auto-wrapped to a single-element array. Comparison is case-insensitive and accent-insensitive." } }, "required": [ "operator", "path", "value" ], "additionalProperties": false, "description": "Array containment filter for array-typed attributes (e.g. tags). Matches entities where the field contains ALL of the specified values. Example: `{\"operator\": \"cs\", \"path\": [\"attributes\", \"tags\"], \"value\": [\"urgent\", \"review\"]}` finds entities tagged with both urgent AND review." }, "OverlapsFilter": { "type": "object", "properties": { "operator": { "type": "string", "const": "ov", "description": "Must be \"ov\"" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to filter on. Single element for entity-level fields: [\"name\"], [\"id\"], [\"created_at\"], [\"updated_at\"]. Two elements for indexed attributes: [\"attributes\", \"status\"]. Relationship fields are keyed by the RELATED ENTITY TYPE NAME (not the rule name), in EITHER direction (the engine resolves the connecting rule from→to or to→from): [\"relationships\", \"\", \"attributes\", \"field\"]. (Rule-name filtering uses the special form [\"relationships\", \"rule\", \"name\"].)" }, "value": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "number" } } ], "description": "Array of values; matches if the field shares ANY value with this array. Comparison is case-insensitive and accent-insensitive." } }, "required": [ "operator", "path", "value" ], "additionalProperties": false, "description": "Array overlap filter for array-typed attributes. Matches entities where the field contains ANY of the specified values (logical OR). Example: `{\"operator\": \"ov\", \"path\": [\"attributes\", \"tags\"], \"value\": [\"urgent\", \"critical\"]}` finds entities tagged with urgent OR critical." }, "LikeFilter": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "like", "ilike" ], "description": "\"like\" is case-sensitive and accent-insensitive; \"ilike\" is case-insensitive and accent-insensitive. Both match against a pre-normalized (unaccented) column, so accent-insensitivity applies to both. Use \"ilike\" for case-tolerant search (most UI search boxes); \"like\" when case carries meaning (e.g. country codes, identifier prefixes)." }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to filter on. Single element for entity-level fields: [\"name\"], [\"id\"], [\"created_at\"], [\"updated_at\"]. Two elements for indexed attributes: [\"attributes\", \"status\"]. Relationship fields are keyed by the RELATED ENTITY TYPE NAME (not the rule name), in EITHER direction (the engine resolves the connecting rule from→to or to→from): [\"relationships\", \"\", \"attributes\", \"field\"]. (Rule-name filtering uses the special form [\"relationships\", \"rule\", \"name\"].)" }, "value": { "type": "string", "description": "Text pattern to match against. Use \"%\" as wildcard. \"prefix%\" for starts-with, \"%suffix\" for ends-with, \"%substring%\" for contains." } }, "required": [ "operator", "path", "value" ], "additionalProperties": false, "description": "Pattern matching filter. Both operators match against a pre-normalized (unaccented) column, so accent-insensitivity is shared. The difference is case: \"like\" preserves case, \"ilike\" lowercases both sides. Prefix patterns (e.g. \"Joh%\") are index-optimized. Example: `{\"operator\": \"ilike\", \"path\": [\"attributes\", \"email\"], \"value\": \"%@example.com\"}` finds entities with example.com email addresses regardless of case." }, "SegmentFilter": { "type": "object", "properties": { "operator": { "type": "string", "const": "segment", "description": "Must be \"segment\"" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to filter on. Single element for entity-level fields: [\"name\"], [\"id\"], [\"created_at\"], [\"updated_at\"]. Two elements for indexed attributes: [\"attributes\", \"status\"]. Relationship fields are keyed by the RELATED ENTITY TYPE NAME (not the rule name), in EITHER direction (the engine resolves the connecting rule from→to or to→from): [\"relationships\", \"\", \"attributes\", \"field\"]. (Rule-name filtering uses the special form [\"relationships\", \"rule\", \"name\"].)" }, "value": { "type": "string", "description": "Segment value to search for within a pipe-delimited string. Case-insensitive. Do not include the pipe delimiters — just the segment value (e.g. \"tag2\")." } }, "required": [ "operator", "path", "value" ], "additionalProperties": false, "description": "Segment matching filter for pipe-delimited text fields. Values are stored as |seg1|seg2|seg3| and this filter matches entities containing the specified segment. Example: `{\"operator\": \"segment\", \"path\": [\"identifier_key\"], \"value\": \"imo9001001\"}` finds entities with \"|imo9001001|\" as the identifier key." }, "FuzzyFilter": { "type": "object", "properties": { "operator": { "type": "string", "const": "fuzzy", "description": "Must be \"fuzzy\"" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to filter on. Single element for entity-level fields: [\"name\"], [\"id\"], [\"created_at\"], [\"updated_at\"]. Two elements for indexed attributes: [\"attributes\", \"status\"]. Relationship fields are keyed by the RELATED ENTITY TYPE NAME (not the rule name), in EITHER direction (the engine resolves the connecting rule from→to or to→from): [\"relationships\", \"\", \"attributes\", \"field\"]. (Rule-name filtering uses the special form [\"relationships\", \"rule\", \"name\"].)" }, "value": { "type": "string", "minLength": 1, "description": "Search term for fuzzy matching. Typos and near-matches will be included in results. Matching is case-insensitive and accent-insensitive. Uses word-similarity matching, so multi-value text columns (e.g. comma-separated lists) score against the best-matching entry rather than the whole string." }, "threshold": { "description": "Word-similarity threshold between 0 and 1. Default is 0.6. Higher values require closer matches (e.g., 0.8 for strict matching, 1.0 for exact). Lower values allow more typos.", "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "operator", "path", "value" ], "additionalProperties": false, "description": "Fuzzy text search for approximate matching. Example: `{\"operator\": \"fuzzy\", \"path\": [\"attributes\", \"company_name\"], \"value\": \"Gogle\"}` matches \"Google\" despite the typo. Optionally set threshold (0-1) for stricter or looser matching." }, "ExistsFilter": { "type": "object", "properties": { "operator": { "type": "string", "const": "exists", "description": "Must be \"exists\"" }, "path": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "string" }, "description": "Path to a relationship type. Must be [\"relationships\", \"\"]. Checks whether the entity has at least one relationship of this type." } }, "required": [ "operator", "path" ], "additionalProperties": false, "description": "Relationship existence filter. Returns entities that have at least one relationship to the specified entity type. Example: `{\"operator\": \"exists\", \"path\": [\"relationships\", \"VesselCertificate\"]}` returns vessels that have certificates." }, "RelExistsFilter": { "type": "object", "properties": { "operator": { "type": "string", "const": "rel_exists", "description": "Must be \"rel_exists\"" }, "path": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "string" }, "description": "Path to a relationship type. Must be [\"relationships\", \"\"]." }, "value": { "description": "Optional nested filter. Unlike scalar `value` on other particle filters, this is a ROW-SET predicate — every leaf must match the SAME related row (conjoint-row guarantee, vs the loose AND-of-EXISTS you'd get from two `[relationships,T,attributes,X]` filters at the parent level). When omitted, `rel_exists` behaves like the legacy `exists` operator. Can itself contain `rel_exists` for depth-2+ path filtering.", "anyOf": [ { "$ref": "#/components/schemas/ParticleFilter" }, { "$ref": "#/components/schemas/__schema11" } ] } }, "required": [ "operator", "path" ], "additionalProperties": false }, "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema0" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } } ] }, "SortSpec": { "type": "object", "properties": { "path": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Property path to sort by. Supports entity-level fields ([\"created_at\"], [\"updated_at\"]) and attribute paths ([\"attributes\", \"priority\"]). Attribute paths must be configured as an indexed attribute." }, "direction": { "default": "asc", "description": "Sort direction (default: \"asc\")", "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "path", "direction" ], "additionalProperties": false, "description": "Single sort specification. Multiple sort specs are applied in order (primary sort first). If no sort is provided, the default is created_at descending." }, "BulkExportCsv": { "type": "object", "properties": { "type_name": { "type": "string", "minLength": 1 }, "filter": { "default": { "operator": "and", "filters": [] }, "anyOf": [ { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "and", "or", "not" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ParticleFilter" }, { "$ref": "#/components/schemas/__schema0" } ] } } }, "required": [ "operator", "filters" ], "additionalProperties": false }, { "$ref": "#/components/schemas/ParticleFilter" } ] }, "sort": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/SortSpec" } }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "columns": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 } }, "array_strategy": { "type": "string", "enum": [ "first_only", "json_array", "comma_separated" ] }, "delimiter": { "type": "string" }, "output_filename": { "type": "string" }, "batch_size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type_name", "columns" ], "additionalProperties": false }, "CreateUploadUrlRequest": { "type": "object", "properties": { "artifact_type": { "type": "string", "minLength": 1 }, "upsert": { "default": false, "type": "boolean" }, "compression_type": { "type": "string", "enum": [ "none", "gzip", "zstd", "brotli" ] }, "metadata": { "default": {}, "type": "object", "additionalProperties": {}, "description": "Artifact metadata key-value pairs" }, "expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "make_public": { "default": false, "type": "boolean" }, "file_name": { "type": "string" }, "file_content_type": { "type": "string" } }, "required": [ "artifact_type", "upsert", "metadata", "make_public" ], "additionalProperties": false }, "CreateUploadUrlResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "artifact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "artifact_version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "upload_url": { "type": "string", "format": "uri" }, "token": { "type": "string" }, "path": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "artifact_id", "artifact_version", "upload_url", "token", "path", "expires_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "ConfirmUploadResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "artifact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "artifact_type": { "type": "string" }, "artifact_version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "storage_key": { "type": "string" }, "file_id": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "public_url": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "artifact_id", "entity_id", "artifact_type", "artifact_version", "storage_key", "file_id", "size", "content_type", "checksum", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "EntityArtifact": { "type": "object", "properties": { "artifact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "artifact_type": { "type": "string" }, "artifact_version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "original_filename": { "type": "string" }, "content_type": { "type": "string" }, "file_size_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Artifact metadata key-value pairs" }, "storage_key": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "accessed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "artifact_id", "entity_id", "artifact_type", "artifact_version", "original_filename", "content_type", "file_size_bytes", "metadata", "created_at", "updated_at", "accessed_at", "expires_at" ], "additionalProperties": false }, "ListEntityArtifactsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityArtifact" } }, "total_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "total_count" ], "additionalProperties": false }, "CreateDownloadUrlResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri" } }, "required": [ "download_url" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "BulkDeleteEntityArtifactsRequest": { "type": "object", "properties": { "artifact_type": { "type": "string", "minLength": 1 } }, "required": [ "artifact_type" ], "additionalProperties": false }, "BulkDeleteEntityArtifactsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deleted_artifact_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } } }, "required": [ "deleted_count", "deleted_artifact_ids" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "CreateShare": { "type": "object", "properties": { "grantee_tenant_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "permitted_actions": { "default": [ "read" ], "type": "array", "items": { "type": "string", "const": "read" } }, "is_active": { "default": true, "type": "boolean" } }, "required": [ "grantee_tenant_id", "permitted_actions", "is_active" ], "additionalProperties": false }, "UpdateShare": { "type": "object", "properties": { "permitted_actions": { "type": "array", "items": { "type": "string", "const": "read" } }, "is_active": { "type": "boolean" } }, "additionalProperties": false }, "EntityType": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attributes_schema_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Entity type configuration" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "source_type": { "type": "string", "enum": [ "shared", "owned" ] } }, "required": [ "id", "name", "description", "attributes_schema_id", "config", "status", "created_at", "updated_at", "source_type" ], "additionalProperties": false }, "ItemLifecycleStatus": { "type": "string", "enum": [ "draft", "active", "deprecated", "inactive", "archived" ], "description": "Lifecycle status of a catalog item — draft (not yet active), active (in use), deprecated (discouraged but still valid), inactive (disabled), archived (retired)." }, "ListEntityTypesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityType" } } }, "required": [ "data" ], "additionalProperties": false }, "EntityTypeConfig": { "type": "object", "properties": { "identifier_key": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "transform": { "default": "alphanumeric", "type": "string", "enum": [ "alphanumeric", "none" ] }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "on_null": { "default": "raise", "type": "string", "enum": [ "raise", "skip" ] } }, "required": [ "path", "on_null" ], "additionalProperties": false } } }, "required": [ "enabled", "transform" ], "additionalProperties": false }, "name": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "separator": { "default": " ", "type": "string" }, "transform": { "default": "none", "type": "string", "enum": [ "none", "title_case", "lowercase", "uppercase" ] }, "attributes": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string" } }, "on_null": { "default": "skip", "type": "string", "enum": [ "skip", "empty" ] } }, "required": [ "path", "on_null" ], "additionalProperties": false } } }, "required": [ "enabled", "separator", "transform" ], "additionalProperties": false }, "indexed_attributes": { "default": [], "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/IndexedAttributeConfig" } } }, "required": [ "indexed_attributes" ], "additionalProperties": false }, "IndexedAttributeConfig": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "text", "numeric", "timestamptz", "boolean", "text_array" ] }, "filterable": { "default": true, "type": "boolean" }, "sortable": { "default": false, "type": "boolean" }, "searchable": { "default": false, "type": "boolean" } }, "required": [ "path", "type", "filterable", "sortable", "searchable" ], "additionalProperties": false }, "CreateEntityType": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-zA-Z][a-zA-Z0-9 ]*$" }, "description": { "default": "", "type": "string" }, "attributes_schema_name": { "type": "string", "minLength": 1 }, "attributes_schema_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "config": { "$ref": "#/components/schemas/EntityTypeConfig" } }, "required": [ "name", "description", "config" ], "additionalProperties": false }, "GetEntityTypeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EntityType" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateEntityType": { "type": "object", "properties": { "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" }, "config": { "$ref": "#/components/schemas/EntityTypeConfig" } }, "required": [ "config" ], "additionalProperties": false }, "PatchEntityTypeConfig": { "type": "object", "properties": { "identifier_key": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "transform": { "default": "alphanumeric", "type": "string", "enum": [ "alphanumeric", "none" ] }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "on_null": { "default": "raise", "type": "string", "enum": [ "raise", "skip" ] } }, "required": [ "path", "on_null" ], "additionalProperties": false } } }, "required": [ "enabled", "transform" ], "additionalProperties": false }, "name": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "separator": { "default": " ", "type": "string" }, "transform": { "default": "none", "type": "string", "enum": [ "none", "title_case", "lowercase", "uppercase" ] }, "attributes": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string" } }, "on_null": { "default": "skip", "type": "string", "enum": [ "skip", "empty" ] } }, "required": [ "path", "on_null" ], "additionalProperties": false } } }, "required": [ "enabled", "separator", "transform" ], "additionalProperties": false }, "indexed_attributes": { "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/IndexedAttributeConfig" } } }, "additionalProperties": false }, "JobStatusResponse": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false }, "CreateResourceGrant": { "type": "object", "properties": { "grantee_kind": { "type": "string", "enum": [ "user", "team", "policy" ] }, "grantee_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "default": [ "read" ], "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } }, "is_active": { "default": true, "type": "boolean" } }, "required": [ "grantee_kind", "grantee_id", "actions", "is_active" ], "additionalProperties": false }, "UpdateGrant": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } }, "is_active": { "type": "boolean" } }, "additionalProperties": false }, "RelationshipRule": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "from_entity_type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "to_entity_type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "semantic_label": { "type": "string" }, "inverse_semantic_label": { "type": "string" }, "is_symmetric": { "type": "boolean" }, "attributes_schema_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "validation_rules": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Relationship validation rules" }, { "type": "null" } ] }, "max_from_cardinality": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "max_to_cardinality": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "source_type": { "type": "string", "enum": [ "shared", "owned" ] } }, "required": [ "id", "name", "description", "from_entity_type", "to_entity_type", "semantic_label", "inverse_semantic_label", "is_symmetric", "attributes_schema_id", "validation_rules", "max_from_cardinality", "max_to_cardinality", "status", "created_at", "updated_at", "source_type" ], "additionalProperties": false }, "ListRelationshipRulesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipRule" } } }, "required": [ "data" ], "additionalProperties": false }, "CreateRelationshipRule": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[a-zA-Z][a-zA-Z0-9_ ]*$" }, "description": { "type": "string" }, "from_entity_type_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "to_entity_type_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "semantic_label": { "type": "string", "minLength": 1 }, "inverse_semantic_label": { "type": "string", "minLength": 1 }, "is_symmetric": { "default": false, "type": "boolean" }, "attributes_schema_name": { "type": "string" }, "max_from_cardinality": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "max_to_cardinality": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "from_entity_type_id", "to_entity_type_id", "semantic_label", "inverse_semantic_label", "is_symmetric" ], "additionalProperties": false }, "GetRelationshipRuleResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RelationshipRule" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateRelationshipRule": { "type": "object", "properties": { "description": { "type": "string" }, "semantic_label": { "type": "string", "minLength": 1 }, "inverse_semantic_label": { "type": "string", "minLength": 1 }, "max_from_cardinality": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "max_to_cardinality": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" } }, "additionalProperties": false }, "RelationshipInstance": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "from_entity": { "$ref": "#/components/schemas/Entity" }, "to_entity": { "$ref": "#/components/schemas/Entity" }, "type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "attributes_schema_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] } }, "required": [ "id", "name", "attributes_schema_id" ], "additionalProperties": false }, "attributes": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Relationship instance attributes" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "from_entity", "to_entity", "type", "attributes", "created_at", "updated_at" ], "additionalProperties": false }, "ListRelationshipInstancesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipInstance" } } }, "required": [ "data" ], "additionalProperties": false }, "CreateRelationshipInstance": { "type": "object", "properties": { "from_entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "to_entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "rule_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "attributes": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Relationship instance attributes" }, { "type": "null" } ] }, "on_cardinality_violation": { "default": "raise", "description": "Strategy when a write would exceed the rule's max_from_cardinality / max_to_cardinality. `raise` → HTTP 409 Conflict (\"Cardinality constraint violated\"). `replace` → soft-delete the oldest existing relationship to make room. `ignore` → silently skip the write (single create returns HTTP 422 with an actionable message naming the strategy knob, never 503).", "type": "string", "enum": [ "raise", "replace", "ignore" ] } }, "required": [ "from_entity_id", "to_entity_id", "rule_id", "on_cardinality_violation" ], "additionalProperties": false }, "GetRelationshipInstanceResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RelationshipInstance" } }, "required": [ "data" ], "additionalProperties": false }, "UpsertRelationshipInstances": { "type": "object", "properties": { "rule_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "rule_name": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "from_entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "to_entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "rule_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "rule_name": { "type": "string" }, "attributes": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Relationship instance attributes" }, { "type": "null" } ] } }, "required": [ "from_entity_id", "to_entity_id" ], "additionalProperties": false } }, "on_conflict": { "default": "replace", "type": "string", "enum": [ "raise", "ignore", "merge", "replace" ] }, "on_cardinality_violation": { "default": "replace", "description": "Per-row strategy when a write would exceed the rule's max_from_cardinality / max_to_cardinality. `raise` → HTTP 409 Conflict (\"Cardinality constraint violated\"). `replace` → soft-delete the oldest existing relationship to make room. `ignore` → silently skip the offending rows in the batch.", "type": "string", "enum": [ "raise", "replace", "ignore" ] }, "suppress_events": { "default": false, "type": "boolean" } }, "required": [ "data", "on_conflict", "on_cardinality_violation", "suppress_events" ], "additionalProperties": false }, "UpsertRelationshipInstancesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "from_entity": { "$ref": "#/components/schemas/Entity" }, "to_entity": { "$ref": "#/components/schemas/Entity" }, "type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "attributes_schema_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] } }, "required": [ "id", "name", "attributes_schema_id" ], "additionalProperties": false }, "attributes": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Relationship instance attributes" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "operation_type": { "type": "string", "enum": [ "created", "updated", "ignored" ] }, "original": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Original relationship instance data before modification" }, { "type": "null" } ] } }, "required": [ "id", "from_entity", "to_entity", "type", "attributes", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "SetRelationshipInstances": { "type": "object", "properties": { "entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "rule_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "rule_name": { "type": "string" }, "direction": { "default": "from", "description": "`from` (default): `entity_id` is the rule's from-side and `target_ids` are to-entities. `to` reverses that. The set-replace scopes strictly to the declared side.", "type": "string", "enum": [ "from", "to" ] }, "target_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "suppress_events": { "default": false, "type": "boolean" } }, "required": [ "entity_id", "direction", "target_ids", "suppress_events" ], "additionalProperties": false }, "SetRelationshipInstancesResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "removed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "kept": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "added", "removed", "kept" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "BulkDeleteRelationshipInstances": { "type": "object", "properties": { "relationship_instance_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "suppress_events": { "default": true, "type": "boolean" } }, "required": [ "relationship_instance_ids", "suppress_events" ], "additionalProperties": false }, "DeleteRelationshipInstanceResult": { "type": "object", "properties": { "relationship_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "rule_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "from_entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "to_entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "required": [ "relationship_id", "rule_id", "from_entity_id", "to_entity_id" ], "additionalProperties": false }, "BulkDeleteRelationshipInstancesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeleteRelationshipInstanceResult" } } }, "required": [ "data" ], "additionalProperties": false }, "DeleteRelationshipInstanceResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeleteRelationshipInstanceResult" } }, "required": [ "data" ], "additionalProperties": false }, "CompositeFilter": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "and", "or", "not" ], "description": "Logical combiner. \"and\": all filters must match. \"or\": at least one filter must match. \"not\": inverts the combined result." }, "filters": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ParticleFilter" }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "and", "or", "not" ] }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/ParticleFilter" } } }, "required": [ "operator", "filters" ], "additionalProperties": false, "description": "Nested composite filter (one level deep)" } ] }, "description": "Array of filters to combine. Can mix particle filters and one level of nested composite filters." } }, "required": [ "operator", "filters" ], "additionalProperties": false, "description": "Logical filter that combines multiple particle filters with and/or/not logic. Supports one level of nesting for complex queries. Example: `{\"operator\": \"and\", \"filters\": [{\"operator\": \"eq\", \"path\": [\"attributes\", \"status\"], \"value\": \"active\"}, {\"operator\": \"or\", \"filters\": [{\"operator\": \"gte\", \"path\": [\"attributes\", \"priority\"], \"value\": 5}, {\"operator\": \"eq\", \"path\": [\"attributes\", \"flagged\"], \"value\": true}]}]}` — matches active entities that are high-priority OR flagged." }, "DistinctOn": { "type": "object", "properties": { "paths": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "description": "Property paths to group by (1–5). Each path follows the same format as filter paths. Example: [[\"attributes\", \"category\"]] groups by category; [[\"attributes\", \"region\"], [\"attributes\", \"status\"]] groups by the combination of region and status." }, "sort": { "description": "Sort within each distinct group to control which entity is selected as the representative. Default direction: \"desc\". Example: sort by [\"updated_at\"] desc to get the most recently updated entity per group.", "type": "object", "properties": { "path": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "direction": { "default": "desc", "description": "Sort direction within the distinct group (default: \"desc\").", "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "path", "direction" ], "additionalProperties": false } }, "required": [ "paths" ], "additionalProperties": false, "description": "Distinct grouping, returning one entity per unique combination of the specified attribute paths. Useful for deduplication or getting the latest per attribute path pattern." }, "QueryFilters": { "type": "object", "properties": { "type_name": { "description": "Entity type name to query. Provide this OR entity_type_id (or a top-level eq filter on [\"type\", \"name\"]).", "type": "string" }, "entity_type_id": { "description": "Entity type id to query. The partition key — supplying it prunes to one partition without a name lookup. Alternative to type_name.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "filter": { "description": "Filter criteria. Can be a single particle filter or a composite filter with and/or/not logic. Defaults to an empty AND filter (matches all).", "anyOf": [ { "$ref": "#/components/schemas/ParticleFilter" }, { "$ref": "#/components/schemas/CompositeFilter" } ] }, "sort": { "default": [], "description": "Sort specifications applied in order. Default: [{path: [\"created_at\"], direction: \"desc\"}]", "type": "array", "items": { "$ref": "#/components/schemas/SortSpec" } }, "page": { "default": 1, "description": "Page number for offset pagination. Mutually exclusive with cursor.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "default": 100, "description": "Maximum results per page (1–1000, default: 100)", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 }, "cursor": { "description": "Base64url-encoded keyset pagination cursor from a previous response's next_cursor. Mutually exclusive with page > 1. Provides stable, performant pagination.", "type": "string" }, "include": { "default": [], "description": "Relationship rule names to include in results, e.g. [\"belongs_to\", \"assigned_to\"]. Empty array = no relationships loaded.", "type": "array", "items": { "type": "string" } }, "include_count": { "default": false, "description": "Whether to return a total count of matching entities. Adds a COUNT(*) query — avoid on large datasets.", "type": "boolean" }, "max_relationships": { "default": 100, "description": "Maximum relationships to load per entity per rule (1–1000, default: 100)", "type": "integer", "minimum": 1, "maximum": 1000 }, "distinct_on": { "description": "Group results by distinct values of specified paths. Enables SELECT DISTINCT ON behavior.", "$ref": "#/components/schemas/DistinctOn" } }, "required": [ "sort", "page", "limit", "include", "include_count", "max_relationships" ], "additionalProperties": false, "description": "Query request body for flexible entity searching. Supports composite filters, keyset/offset pagination, multi-column sorting, relationship inclusion, and distinct grouping." }, "QueryEntity": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity ID" }, "type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity type ID" }, "name": { "type": "string", "description": "Entity type name" } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Entity type reference" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Entity display name" }, "identifier_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Unique human-readable identifier" }, "attributes": { "type": "object", "additionalProperties": {}, "description": "Entity attributes (key-value pairs)" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Last update timestamp" }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Relationship rule ID" }, "name": { "type": "string", "description": "Relationship rule name" } }, "required": [ "id", "name" ], "additionalProperties": false }, "entity": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "type": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "identifier_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attributes": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "name", "identifier_key", "attributes" ], "additionalProperties": false, "description": "Related entity (without nested relationships)" }, "direction": { "description": "Relationship direction relative to this entity", "type": "string", "enum": [ "from", "to" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "rule", "entity", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Included relationships (populated via include parameter)" } }, "required": [ "id", "type", "name", "identifier_key", "attributes", "created_at", "updated_at", "relationships" ], "additionalProperties": false, "description": "Entity with optional relationship data" }, "QueryResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/QueryEntity" }, "description": "Array of matching entities" }, "count": { "description": "Total count of matching entities (only present when include_count: true). Default is capped at 10000.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "next_cursor": { "description": "Keyset pagination cursor for the next page. Pass this as the cursor parameter in the next request. Absent when there are no more results.", "type": "string" } }, "required": [ "data" ], "additionalProperties": false, "description": "Paginated query response" }, "DistinctValuesRequest": { "type": "object", "properties": { "type_name": { "type": "string", "minLength": 1, "description": "Entity type name" }, "attribute_name": { "type": "string", "minLength": 1, "description": "Indexed attribute to get distinct values from" }, "search": { "description": "Optional text filter on the values (case-insensitive)", "type": "string" }, "limit": { "default": 100, "description": "Maximum number of distinct values (1–1000, default: 100)", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "type_name", "attribute_name", "limit" ], "additionalProperties": false, "description": "Request to retrieve distinct values for a single indexed attribute, with optional text search." }, "DistinctValuesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" }, "description": "Array of distinct attribute values" } }, "required": [ "data" ], "additionalProperties": false, "description": "Distinct values response" }, "__schema1": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema1" } } ] }, "EntityEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "category": { "type": "string" }, "entity_type_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "relationship_rule_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "entity_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "event_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payload": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Event payload data" }, { "type": "null" } ] }, "created_at": { "type": "string" } }, "required": [ "id", "category", "entity_type_id", "relationship_rule_id", "entity_id", "event_action", "payload", "created_at" ], "additionalProperties": false }, "ListEventsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityEvent" } } }, "required": [ "data" ], "additionalProperties": false }, "GetEventResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EntityEvent" } }, "required": [ "data" ], "additionalProperties": false }, "CreateWorkflowDefinition": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "label": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "default": "draft", "$ref": "#/components/schemas/ItemLifecycleStatus" }, "source_yaml": { "type": "string", "minLength": 1 }, "definition_json": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "status" ], "additionalProperties": false }, "Workflow": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "label": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "source_yaml": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "definition_json": { "$ref": "#/components/schemas/WorkflowDefinitionV1" }, "source_type": { "type": "string", "enum": [ "owned", "shared" ] }, "config": { "$ref": "#/components/schemas/WorkflowConfig" } }, "required": [ "id", "name", "label", "description", "status", "created_at", "updated_at", "definition_json", "source_type", "config" ], "additionalProperties": false }, "WorkflowDefinitionV1": { "type": "object", "properties": { "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerDefinition" }, "description": "Trigger definitions for this workflow" }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/JobStepDefinition" }, "description": "Job step definitions (execution graph)" }, "controls": { "default": { "concurrency": { "workflow": { "limit": 1, "policy": "queue" }, "idempotencyKey": { "policy": "queue" } }, "retry": { "success": "restart", "error": "restart", "cancel": "restart" } }, "type": "object", "properties": { "concurrency": { "default": { "workflow": { "limit": 1, "policy": "queue" }, "idempotencyKey": { "policy": "queue" } }, "description": "Concurrency controls", "type": "object", "properties": { "workflow": { "default": { "limit": 1, "policy": "queue" }, "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Global concurrency limit — must be >= 1. Default 1 = serialized execution. For 'effectively unlimited' use a large value." }, "policy": { "type": "string", "enum": [ "skip", "queue" ], "description": "What to do when limit is reached (default: queue)" } }, "required": [ "limit", "policy" ], "additionalProperties": false }, "idempotencyKey": { "default": { "policy": "queue" }, "type": "object", "properties": { "policy": { "type": "string", "enum": [ "skip", "queue" ], "description": "Policy for idempotency key collisions (default: queue, limit is fixed at 1)" } }, "required": [ "policy" ], "additionalProperties": false } }, "required": [ "workflow", "idempotencyKey" ], "additionalProperties": false }, "retry": { "default": { "success": "restart", "error": "restart", "cancel": "restart" }, "description": "Retry/rerun controls", "type": "object", "properties": { "success": { "default": "restart", "description": "Rerun policy for successful workflows", "type": "string", "enum": [ "restart", "none" ] }, "error": { "default": "restart", "description": "Rerun policy for errored workflows", "type": "string", "enum": [ "resume", "restart", "none" ] }, "cancel": { "default": "restart", "description": "Rerun policy for cancelled workflows", "type": "string", "enum": [ "resume", "restart", "none" ] } }, "required": [ "success", "error", "cancel" ], "additionalProperties": false } }, "required": [ "concurrency", "retry" ], "additionalProperties": false }, "config": { "default": { "env": {} }, "type": "object", "properties": { "env": { "type": "object", "additionalProperties": {}, "description": "Environment variables — null values must be set as tenant-specific config" } }, "required": [ "env" ], "additionalProperties": false }, "policy": { "description": "Optional default policy block. Activate-time materialises this into the consumer tenant and binds it to the workflow_token.", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "grants": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string" }, "resourceId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } } }, "required": [ "resourceType", "resourceId", "actions" ], "additionalProperties": false } } }, "required": [ "name", "grants" ], "additionalProperties": false }, "shares": { "description": "Optional cross-tenant shares. The workflow's derived manifest fans these out into resource_share rows for every tenant the workflow is shared with; activating the workflow subscribes the consumer so the rows materialise.", "type": "object", "properties": { "entityTypes": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "jsonSchemas": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "entities": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "entityType": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "scope": { "type": "string", "const": "all" } }, "required": [ "entityType", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "entityType": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "scope": { "type": "string", "const": "specific" }, "entityIds": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } } }, "required": [ "entityType", "scope", "entityIds" ], "additionalProperties": false }, { "type": "object", "properties": { "entityType": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "scope": { "type": "string", "const": "filter" }, "attributeFilter": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "value": {} }, "required": [ "operator", "path", "value" ], "additionalProperties": false } } }, "required": [ "entityType", "scope", "attributeFilter" ], "additionalProperties": false } ] } } }, "additionalProperties": false } }, "required": [ "triggers", "jobs", "controls", "config" ], "additionalProperties": false }, "TriggerDefinition": { "type": "object", "properties": { "id": { "type": "string", "description": "Trigger identifier" }, "inputSchemaName": { "description": "Schema name for input validation (only if workflow accepts input besides the source entity)", "type": "string" }, "source": { "description": "Entity/event source binding (not available for cron or webhook triggers)", "type": "object", "properties": { "entityTypeId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Entity type ID" }, "relationshipRuleId": { "description": "Optional relationship rule ID", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "entityId": { "description": "Entity ID — omitted means it will be provided at trigger time", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "eventAction": { "type": "string", "description": "Event action name that activates this trigger" }, "attributeFilters": { "description": "Attribute filters — workflow only triggers if the source entity matches these filters", "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "is", "like", "ilike", "cs", "ov" ] }, "path": { "type": "array", "items": { "type": "string" } }, "value": {} }, "required": [ "operator", "path", "value" ], "additionalProperties": false } } }, "required": [ "entityTypeId", "eventAction" ], "additionalProperties": false }, "condition": { "description": "Bare JSONata predicate expression (or `{ $jsonata: … }`)", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "$jsonata": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } } ] } }, "required": [ "$jsonata" ], "additionalProperties": false, "description": "JSONata value directive — the typed/RAW value tool. A string is one expression → raw value (NOT the same as a whole-string `{{ }}`, which stringifies). An object/array is deep-evaluated where every string leaf is a JSONata expression; author a literal string with a JSONata string literal (\"'hello'\") or `$literal`." } ] }, "contextData": { "description": "Smart-value for the workflow's context data. May be a string (bare literal or `{{ }}` expression) OR an inline object / array literal whose leaves carry `{{ }}` smart values. Must resolve to an object.", "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema2" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema3" } } ] }, "idempotencyKey": { "description": "Smart-value `{{ }}` expression for idempotency key (default: workflow_id + source_entity_id)", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "$jsonata": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } } ] } }, "required": [ "$jsonata" ], "additionalProperties": false, "description": "JSONata value directive — the typed/RAW value tool. A string is one expression → raw value (NOT the same as a whole-string `{{ }}`, which stringifies). An object/array is deep-evaluated where every string leaf is a JSONata expression; author a literal string with a JSONata string literal (\"'hello'\") or `$literal`." } ] }, "cron": { "description": "Cron expression for scheduled triggers", "type": "string" }, "webhook": { "description": "Webhook trigger configuration", "type": "object", "properties": { "methods": { "description": "Allowed HTTP methods (default: [\"POST\"])", "type": "array", "items": { "type": "string", "enum": [ "GET", "POST" ] } }, "verification": { "description": "Request verification configuration", "type": "object", "properties": { "location": { "type": "string", "enum": [ "body", "query", "header" ], "description": "Where to find the verification value" }, "key": { "type": "string", "description": "Path/key to the verification value (dot-notation for body, param name for query, header name for header)" }, "method": { "type": "string", "enum": [ "exact", "hmac-sha256", "hmac-sha1" ], "description": "Verification method" } }, "required": [ "location", "key", "method" ], "additionalProperties": false }, "challenge": { "description": "Challenge-response configuration for endpoint validation", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Enable challenge-response validation flow" }, "queryParam": { "type": "string", "description": "Query parameter containing the challenge token (e.g. \"validationToken\")" }, "responseType": { "type": "string", "enum": [ "text/plain", "application/json" ], "description": "Response content type" }, "responseKey": { "description": "For JSON responses, the key to wrap the challenge in (e.g. \"challenge\")", "type": "string" } }, "required": [ "enabled", "queryParam", "responseType" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false }, "__schema2": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema2" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema2" } } ] }, "__schema3": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema3" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema3" } } ] }, "JobStepDefinition": { "anyOf": [ { "$ref": "#/components/schemas/JobStepReference" }, { "$ref": "#/components/schemas/JobStepInline" } ] }, "JobStepReference": { "type": "object", "properties": { "stepId": { "type": "string", "description": "Unique step identifier within the workflow" }, "dependencies": { "description": "Step IDs this job depends on", "type": "array", "items": { "type": "string" } }, "idempotencyKey": { "description": "Smart-value `{{ }}` expression for idempotency key (default: null)", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "$jsonata": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } } ] } }, "required": [ "$jsonata" ], "additionalProperties": false, "description": "JSONata value directive — the typed/RAW value tool. A string is one expression → raw value (NOT the same as a whole-string `{{ }}`, which stringifies). An object/array is deep-evaluated where every string leaf is a JSONata expression; author a literal string with a JSONata string literal (\"'hello'\") or `$literal`." } ] }, "condition": { "description": "Bare JSONata predicate — evaluated before running the job", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "$jsonata": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } } ] } }, "required": [ "$jsonata" ], "additionalProperties": false, "description": "JSONata value directive — the typed/RAW value tool. A string is one expression → raw value (NOT the same as a whole-string `{{ }}`, which stringifies). An object/array is deep-evaluated where every string leaf is a JSONata expression; author a literal string with a JSONata string literal (\"'hello'\") or `$literal`." } ] }, "conditionPolicy": { "description": "What happens when condition evaluates to false (default: fail).", "type": "string", "enum": [ "continue", "abort", "fail" ] }, "errorPolicy": { "description": "What happens when the job fails (default: fail)", "type": "string", "enum": [ "continue", "abort", "fail" ] }, "input": { "description": "Job input — a literal object, or a smart-value `{{ }}` string/object resolved against the workflow context (null if not provided)", "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "$jsonata": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } } ] } }, "required": [ "$jsonata" ], "additionalProperties": false, "description": "JSONata value directive — the typed/RAW value tool. A string is one expression → raw value (NOT the same as a whole-string `{{ }}`, which stringifies). An object/array is deep-evaluated where every string leaf is a JSONata expression; author a literal string with a JSONata string literal (\"'hello'\") or `$literal`." } ] }, { "type": "object", "additionalProperties": {} } ] }, "output": { "description": "Smart-value for the job-step output. String / object / array authoring all accepted; raw result when omitted.", "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema4" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema5" } } ] }, "rerunPolicy": { "description": "Rerun policy (default: allow)", "type": "string", "enum": [ "continue", "allow", "abort" ] }, "name": { "type": "string", "description": "Job definition name" }, "version": { "type": "string", "description": "Job definition version" }, "resolvedJobId": { "description": "Server-stamped: the job id resolved from name@version at definition publish time (create/update). Written by workflow-service's job-ref enrichment; callers never set this — any value supplied on write is discarded and replaced with the freshly resolved id. Absent on legacy definitions not yet republished, which fall back to resolving by name@version.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "stepId", "name", "version" ], "additionalProperties": false }, "__schema4": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema4" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema4" } } ] }, "__schema5": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema5" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema5" } } ] }, "JobStepInline": { "type": "object", "properties": { "stepId": { "type": "string", "description": "Unique step identifier within the workflow" }, "dependencies": { "description": "Step IDs this job depends on", "type": "array", "items": { "type": "string" } }, "idempotencyKey": { "description": "Smart-value `{{ }}` expression for idempotency key (default: null)", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "$jsonata": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } } ] } }, "required": [ "$jsonata" ], "additionalProperties": false, "description": "JSONata value directive — the typed/RAW value tool. A string is one expression → raw value (NOT the same as a whole-string `{{ }}`, which stringifies). An object/array is deep-evaluated where every string leaf is a JSONata expression; author a literal string with a JSONata string literal (\"'hello'\") or `$literal`." } ] }, "condition": { "description": "Bare JSONata predicate — evaluated before running the job", "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "$jsonata": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } } ] } }, "required": [ "$jsonata" ], "additionalProperties": false, "description": "JSONata value directive — the typed/RAW value tool. A string is one expression → raw value (NOT the same as a whole-string `{{ }}`, which stringifies). An object/array is deep-evaluated where every string leaf is a JSONata expression; author a literal string with a JSONata string literal (\"'hello'\") or `$literal`." } ] }, "conditionPolicy": { "description": "What happens when condition evaluates to false (default: fail).", "type": "string", "enum": [ "continue", "abort", "fail" ] }, "errorPolicy": { "description": "What happens when the job fails (default: fail)", "type": "string", "enum": [ "continue", "abort", "fail" ] }, "input": { "description": "Job input — a literal object, or a smart-value `{{ }}` string/object resolved against the workflow context (null if not provided)", "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "$jsonata": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } } ] } }, "required": [ "$jsonata" ], "additionalProperties": false, "description": "JSONata value directive — the typed/RAW value tool. A string is one expression → raw value (NOT the same as a whole-string `{{ }}`, which stringifies). An object/array is deep-evaluated where every string leaf is a JSONata expression; author a literal string with a JSONata string literal (\"'hello'\") or `$literal`." } ] }, { "type": "object", "additionalProperties": {} } ] }, "output": { "description": "Smart-value for the job-step output. String / object / array authoring all accepted; raw result when omitted.", "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema4" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema5" } } ] }, "rerunPolicy": { "description": "Rerun policy (default: allow)", "type": "string", "enum": [ "continue", "allow", "abort" ] }, "actions": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/__schema6" }, "description": "Ordered list of action definitions" }, "outputStreamTransformer": { "description": "Smart-value producing the job-output stream transform (`{ streamId, outputType }` entries). String / array / object authoring all accepted.", "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema13" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema14" } } ] } }, "required": [ "stepId", "actions" ], "additionalProperties": false }, "__schema6": { "$ref": "#/components/schemas/ActionDefinition" }, "ActionDefinition": { "type": "object", "description": "Action definition within a job. Discriminated by the 'name' field. Each action type has a specific config schema. `if`/`errorWhen` are bare JSONata predicates; smart-value fields use `{{ }}` expressions evaluated at runtime.", "required": [ "stepId", "name", "config" ], "properties": { "stepId": { "type": "string", "description": "Unique step identifier" }, "name": { "type": "string", "enum": [ "http", "httpCallback", "llmCallback", "awaitInput", "invokeWorkflow", "queryEntity", "queryEntityGraph", "upsertEntity", "removeEntities", "upsertRelationship", "removeRelationships", "syncRelationships", "zipCompress", "zipDecompress", "archiveDecompress", "uploadArtifact", "downloadArtifact", "createArtifactDownloadURL", "listEntityArtifacts", "csvFromZipStream", "transformCsvStream", "importEntitiesFromCsv", "exportEntitiesToCsv", "splitPdf", "mergePdf", "chunkPdf", "mergeCsvStreams" ], "description": "Action type name" }, "description": { "type": "string", "description": "Human-readable description" }, "config": { "type": "object", "description": "Action-specific configuration (varies by action type)", "additionalProperties": true }, "if": { "type": "string", "description": "Bare JSONata predicate — falsy skips the action and its onSuccess" }, "onSuccess": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Actions run after this action succeeds" }, "onError": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Actions run after this action fails (recovery)" }, "streamTransformer": { "type": "string", "description": "Smart-value `{{ }}` expression to transform stream output" }, "loopOver": { "type": "string", "description": "Smart-value `{{ }}` expression — action executes per array item" }, "output": { "type": "string", "description": "Smart-value `{{ }}` expression for action output" }, "errorWhen": { "type": "string", "description": "Smart-value `{{ }}` predicate — truthy result marks action as failed" }, "errorPolicy": { "type": "string", "enum": [ "fail", "continue" ], "default": "fail", "description": "After this action fails (and its onError runs): `fail` (default) ends the job; `continue` resumes the parent sequence at the next action" } } }, "__schema7": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema7" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema7" } } ] }, "__schema8": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema8" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema8" } } ] }, "__schema9": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema9" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema9" } } ] }, "__schema10": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema10" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema10" } } ] }, "SmartValueDirective": { "anyOf": [ { "type": "object", "properties": { "$literal": {} }, "required": [ "$literal" ], "additionalProperties": false, "description": "Literal escape directive — the wrapped value is returned verbatim, bypassing all smart-value resolution." }, { "type": "object", "properties": { "$jsonata": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema1" } } ] } }, "required": [ "$jsonata" ], "additionalProperties": false, "description": "JSONata value directive — the typed/RAW value tool. A string is one expression → raw value (NOT the same as a whole-string `{{ }}`, which stringifies). An object/array is deep-evaluated where every string leaf is a JSONata expression; author a literal string with a JSONata string literal (\"'hello'\") or `$literal`." } ] }, "__schema11": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "and", "or", "not" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/EqualsFilter" }, { "$ref": "#/components/schemas/IsFilter" }, { "$ref": "#/components/schemas/ComparisonFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/ContainsFilter" }, { "$ref": "#/components/schemas/OverlapsFilter" }, { "$ref": "#/components/schemas/LikeFilter" }, { "$ref": "#/components/schemas/SegmentFilter" }, { "$ref": "#/components/schemas/FuzzyFilter" }, { "$ref": "#/components/schemas/ExistsFilter" } ] }, { "$ref": "#/components/schemas/RelExistsFilter" }, { "$ref": "#/components/schemas/__schema11" } ] } } }, "required": [ "operator", "filters" ], "additionalProperties": false }, "__schema12": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type_name": { "type": "string" }, "rule_name": { "type": "string" }, "filter": { "anyOf": [ { "$ref": "#/components/schemas/ParticleFilter" }, { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "and", "or", "not" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ParticleFilter" }, { "$ref": "#/components/schemas/__schema11" } ] } } }, "required": [ "operator", "filters" ], "additionalProperties": false } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 }, "sort": { "type": "object", "properties": { "path": { "type": "array", "items": { "type": "string" } }, "direction": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "path", "direction" ], "additionalProperties": false }, "include": { "type": "array", "items": { "$ref": "#/components/schemas/__schema12" } }, "as": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "single": { "type": "boolean" } }, "additionalProperties": false } ] }, "__schema13": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema13" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema13" } } ] }, "__schema14": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema14" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema14" } } ] }, "WorkflowConfig": { "type": "object", "properties": { "env": { "description": "Environment variables — null values must be set as tenant-specific config", "type": "object", "additionalProperties": {} } }, "additionalProperties": false }, "GetWorkflowResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workflow" } }, "required": [ "data" ], "additionalProperties": false }, "ListWorkflowsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } } }, "required": [ "data" ], "additionalProperties": false }, "ListWorkflowsByTriggerResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "workflow_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "trigger_definition_id": { "type": "string" }, "trigger_definition_json": { "$ref": "#/components/schemas/TriggerDefinition" }, "trigger_id": { "type": "string" }, "entity_type_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "relationship_rule_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "entity_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "event_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "config": { "$ref": "#/components/schemas/WorkflowConfig" } }, "required": [ "workflow_id", "trigger_definition_id", "trigger_definition_json", "trigger_id", "entity_type_id", "relationship_rule_id", "entity_id", "event_action", "config" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "Job": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "version": { "type": "string" }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "definition_json": { "$ref": "#/components/schemas/JobDefinitionV1" }, "source_type": { "type": "string", "enum": [ "owned", "shared" ] } }, "required": [ "id", "name", "version", "status", "label", "description", "definition_json", "source_type" ], "additionalProperties": false }, "JobDefinitionV1": { "type": "object", "properties": { "inputSchemaName": { "description": "Schema name for input validation", "type": "string" }, "resolvedInputSchemaId": { "description": "Server-stamped: the schema id resolved from inputSchemaName at definition publish time (create/update). Written by workflow-service's job-definition schema-ref enrichment; callers never set this — any value supplied on write is discarded and replaced with the freshly resolved id. Absent when inputSchemaName is unset, or on legacy definitions not yet republished, which fall back to resolving by name.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "output": { "description": "Smart-value for job output. String / object / array authoring all accepted (string may be a bare literal or `{{ }}` expression). Null when omitted.", "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema1" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema2" } } ] }, "outputStreamTransformer": { "description": "Smart-value producing the job-output stream transform (`{ streamId, outputType }` entries). String / array / object authoring all accepted.", "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/__schema3" } }, { "type": "array", "items": { "$ref": "#/components/schemas/__schema4" } } ] }, "outputSchemaName": { "description": "Schema name for output validation (validates the result of `output` or raw output)", "type": "string" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/__schema5" }, "description": "Ordered list of action definitions" } }, "required": [ "actions" ], "additionalProperties": false }, "GetJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" } }, "required": [ "data" ], "additionalProperties": false }, "ListJobsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } }, "required": [ "data" ], "additionalProperties": false }, "ResolveJobsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "version": { "type": "string" }, "definition": { "$ref": "#/components/schemas/JobDefinitionV1" } }, "required": [ "id", "name", "version", "definition" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "ResolveJobResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "version": { "type": "string" }, "definition": { "$ref": "#/components/schemas/JobDefinitionV1" } }, "required": [ "id", "name", "version", "definition" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "WidgetConfig": { "anyOf": [ { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "actions" }, "config": { "type": "object", "additionalProperties": {}, "description": "Open config object carrying smart-values / step-sequences / dataSource — see the widget catalogue (WIDGET-CATALOGUE.md) and SMART-VALUES.md. Documented as an open object because the authored shape is post-eval and smart-value-laden." } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "breadcrumbs" }, "config": { "type": "object", "properties": { "crumbs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "page": { "type": "object", "properties": { "id": { "type": "string" }, "params": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "label" ], "additionalProperties": false } }, "ancestry": { "type": "object", "properties": { "entityType": { "type": "string" }, "entityId": { "type": "string" }, "root": { "type": "object", "properties": { "label": { "type": "string" }, "page": { "type": "object", "properties": { "id": { "type": "string" }, "params": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "label" ], "additionalProperties": false }, "detailPage": { "type": "string" }, "ancestors": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "labelAttr": { "type": "string" } }, "required": [ "type", "labelAttr" ], "additionalProperties": false } }, "self": { "type": "string" } }, "required": [ "entityType", "entityId", "detailPage", "ancestors", "self" ], "additionalProperties": false }, "refresh": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "custom_markup" }, "config": { "type": "object", "additionalProperties": {}, "description": "Open config object carrying smart-values / step-sequences / dataSource — see the widget catalogue (WIDGET-CATALOGUE.md) and SMART-VALUES.md. Documented as an open object because the authored shape is post-eval and smart-value-laden." } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "data_grid" }, "config": { "type": "object", "additionalProperties": {}, "description": "Open config object carrying smart-values / step-sequences / dataSource — see the widget catalogue (WIDGET-CATALOGUE.md) and SMART-VALUES.md. Documented as an open object because the authored shape is post-eval and smart-value-laden." } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "page_tabs" }, "config": { "type": "object", "properties": { "tabs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "page": { "type": "string" }, "children": { "type": "array", "items": { "type": "string" } } }, "required": [ "label", "page" ], "additionalProperties": false } } }, "required": [ "tabs" ], "additionalProperties": false } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "form" }, "config": { "type": "object", "additionalProperties": {}, "description": "Open config object carrying smart-values / step-sequences / dataSource — see the widget catalogue (WIDGET-CATALOGUE.md) and SMART-VALUES.md. Documented as an open object because the authored shape is post-eval and smart-value-laden." } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "header" }, "config": { "type": "object", "properties": { "text": { "type": "string" }, "headerLevel": { "type": "integer", "minimum": 1, "maximum": 3 } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "table" }, "config": { "type": "object", "additionalProperties": {}, "description": "Open config object carrying smart-values / step-sequences / dataSource — see the widget catalogue (WIDGET-CATALOGUE.md) and SMART-VALUES.md. Documented as an open object because the authored shape is post-eval and smart-value-laden." } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "status_checklist" }, "config": { "type": "object", "additionalProperties": {}, "description": "Open config object carrying smart-values / step-sequences / dataSource — see the widget catalogue (WIDGET-CATALOGUE.md) and SMART-VALUES.md. Documented as an open object because the authored shape is post-eval and smart-value-laden." } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "action_bar" }, "config": { "type": "object", "additionalProperties": {}, "description": "Open config object carrying smart-values / step-sequences / dataSource — see the widget catalogue (WIDGET-CATALOGUE.md) and SMART-VALUES.md. Documented as an open object because the authored shape is post-eval and smart-value-laden." } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "related_collections" }, "config": { "type": "object", "properties": { "entityId": { "type": "string" }, "collections": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "type": { "type": "string" }, "via": { "type": "string" }, "columns": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "header": { "type": "string" }, "type": { "default": "string", "type": "string", "enum": [ "string", "number", "date", "dateTime", "boolean", "tag" ] } }, "required": [ "field", "type" ], "additionalProperties": false } }, "noResultsMessage": { "type": "string" } }, "required": [ "label", "type", "via", "columns" ], "additionalProperties": false } }, "collapsible": { "type": "boolean" }, "header": { "type": "string" } }, "required": [ "entityId", "collections" ], "additionalProperties": false } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "entity_info" }, "config": { "type": "object", "properties": { "entityType": { "type": "string" }, "entityId": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "attr": { "type": "string" } }, "required": [ "label", "attr" ], "additionalProperties": false } }, "header": { "type": "string" } }, "required": [ "entityType", "entityId", "fields" ], "additionalProperties": false } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "widgetComponent": { "type": "string", "const": "section_switcher" }, "config": { "type": "object", "properties": { "stateKey": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ], "additionalProperties": false } } }, "required": [ "stateKey", "options" ], "additionalProperties": false } }, "required": [ "widgetComponent", "config" ], "additionalProperties": false } ], "description": "A widget entry in an app spec, discriminated by `widgetComponent`. Light widgets are fully typed; configuration-heavy widgets (steps / dataSource / markup) are shown as open objects — full authoring detail is in the widget catalogue." }, "CreateAppSpec": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "default": "1.0.0", "type": "string", "minLength": 1 }, "spec_document": { "type": "object", "properties": { "dashboards": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "pages": { "type": "object", "additionalProperties": { "type": "object", "properties": { "layout": { "$ref": "#/components/schemas/__schema0" }, "data": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] }, { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] } } ] }, "dataSources": { "type": "object", "additionalProperties": { "type": "object", "properties": {}, "additionalProperties": {} } }, "widgets": { "type": "object", "additionalProperties": { "type": "object", "properties": { "widgetComponent": { "type": "string" }, "config": {} }, "required": [ "widgetComponent" ], "additionalProperties": {} } } }, "required": [ "layout" ], "additionalProperties": {} } }, "defaultPage": { "type": "string" }, "widgets": { "type": "object", "additionalProperties": { "type": "object", "properties": { "widgetComponent": { "type": "string" }, "config": {} }, "required": [ "widgetComponent" ], "additionalProperties": {} } } }, "required": [ "name", "pages" ], "additionalProperties": {} } }, "messages": { "type": "object", "properties": { "pageError": { "type": "string", "minLength": 1 }, "widgetError": { "type": "string", "minLength": 1 }, "validationError": { "type": "string", "minLength": 1 }, "platformError": { "type": "string", "minLength": 1 }, "actionError": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "defaultDashboard": { "type": "string" }, "providers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "bearer" }, "header": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "exchange" }, "trustedAmurlHosts": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "expectedAppctxVersion": { "default": "ExIdTok.V1", "type": "string" }, "allowedAlgorithms": { "default": [ "RS256" ], "minItems": 1, "type": "array", "items": { "type": "string", "const": "RS256" } }, "exchangeIssPrefix": { "default": "00000002-0000-0ff1-ce00-000000000000@", "type": "string" } }, "required": [ "type", "trustedAmurlHosts", "expectedAppctxVersion", "allowedAlgorithms", "exchangeIssPrefix" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oidc" }, "issuerPattern": { "type": "string" }, "audience": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "jwksUriTemplate": { "type": "string", "format": "uri" }, "allowedTidClaim": { "default": "tid", "type": "string" }, "requiredClaims": { "type": "array", "items": { "type": "string" } }, "allowedAlgorithms": { "default": [ "RS256", "ES256" ], "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512" ] } } }, "required": [ "type", "issuerPattern", "audience", "jwksUriTemplate", "allowedTidClaim", "allowedAlgorithms" ], "additionalProperties": false } ] }, "identity": { "type": "object", "additionalProperties": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "body", "header", "query", "jwt_claim" ] }, "path": { "type": "string" } }, "required": [ "source", "path" ], "additionalProperties": false } }, "identityTransforms": { "type": "object", "additionalProperties": { "type": "string" } }, "autoCreateUsers": { "type": "boolean" }, "allowEmailLink": { "type": "boolean" } }, "required": [ "auth", "identity" ], "additionalProperties": false } }, "defaults": { "type": "object", "additionalProperties": {} }, "widgets": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/WidgetConfig" } }, "pages": { "type": "object", "additionalProperties": { "type": "object", "properties": { "layout": { "$ref": "#/components/schemas/__schema0" }, "data": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] }, { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] } } ] }, "dataSources": { "type": "object", "additionalProperties": { "type": "object", "properties": {}, "additionalProperties": {} } }, "widgets": { "type": "object", "additionalProperties": { "type": "object", "properties": { "widgetComponent": { "type": "string" }, "config": {} }, "required": [ "widgetComponent" ], "additionalProperties": {} } } }, "required": [ "layout" ], "additionalProperties": {} } }, "policies": { "type": "object", "additionalProperties": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": "string" }, "grants": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string" }, "resourceId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "string", "const": "$app_config" } ] }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } }, "attributeFilter": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "value": {} }, "required": [ "operator", "path", "value" ], "additionalProperties": false } } }, "required": [ "resourceType", "resourceId", "actions" ], "additionalProperties": false } } }, "required": [ "grants" ], "additionalProperties": false } }, "defaultPolicy": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "shares": { "type": "object", "properties": { "entityTypes": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "jsonSchemas": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "entities": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "entityType": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "scope": { "type": "string", "const": "all" } }, "required": [ "entityType", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "entityType": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "scope": { "type": "string", "const": "specific" }, "entityIds": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } } }, "required": [ "entityType", "scope", "entityIds" ], "additionalProperties": false }, { "type": "object", "properties": { "entityType": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "scope": { "type": "string", "const": "filter" }, "attributeFilter": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "value": {} }, "required": [ "operator", "path", "value" ], "additionalProperties": false } } }, "required": [ "entityType", "scope", "attributeFilter" ], "additionalProperties": false } ] } } }, "additionalProperties": false }, "jobs": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobDefinitionV1" } }, "principalConfigSchemas": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "functions": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "dashboards" ], "additionalProperties": {} } }, "required": [ "name", "version", "spec_document" ], "additionalProperties": false }, "UpdateAppSpec": { "type": "object", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "string", "minLength": 1 }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" }, "spec_document": { "type": "object", "properties": { "dashboards": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "pages": { "type": "object", "additionalProperties": { "type": "object", "properties": { "layout": { "$ref": "#/components/schemas/__schema0" }, "data": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] }, { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] } } ] }, "dataSources": { "type": "object", "additionalProperties": { "type": "object", "properties": {}, "additionalProperties": {} } }, "widgets": { "type": "object", "additionalProperties": { "type": "object", "properties": { "widgetComponent": { "type": "string" }, "config": {} }, "required": [ "widgetComponent" ], "additionalProperties": {} } } }, "required": [ "layout" ], "additionalProperties": {} } }, "defaultPage": { "type": "string" }, "widgets": { "type": "object", "additionalProperties": { "type": "object", "properties": { "widgetComponent": { "type": "string" }, "config": {} }, "required": [ "widgetComponent" ], "additionalProperties": {} } } }, "required": [ "name", "pages" ], "additionalProperties": {} } }, "messages": { "type": "object", "properties": { "pageError": { "type": "string", "minLength": 1 }, "widgetError": { "type": "string", "minLength": 1 }, "validationError": { "type": "string", "minLength": 1 }, "platformError": { "type": "string", "minLength": 1 }, "actionError": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "defaultDashboard": { "type": "string" }, "providers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "bearer" }, "header": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "exchange" }, "trustedAmurlHosts": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "expectedAppctxVersion": { "default": "ExIdTok.V1", "type": "string" }, "allowedAlgorithms": { "default": [ "RS256" ], "minItems": 1, "type": "array", "items": { "type": "string", "const": "RS256" } }, "exchangeIssPrefix": { "default": "00000002-0000-0ff1-ce00-000000000000@", "type": "string" } }, "required": [ "type", "trustedAmurlHosts", "expectedAppctxVersion", "allowedAlgorithms", "exchangeIssPrefix" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "oidc" }, "issuerPattern": { "type": "string" }, "audience": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "jwksUriTemplate": { "type": "string", "format": "uri" }, "allowedTidClaim": { "default": "tid", "type": "string" }, "requiredClaims": { "type": "array", "items": { "type": "string" } }, "allowedAlgorithms": { "default": [ "RS256", "ES256" ], "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512" ] } } }, "required": [ "type", "issuerPattern", "audience", "jwksUriTemplate", "allowedTidClaim", "allowedAlgorithms" ], "additionalProperties": false } ] }, "identity": { "type": "object", "additionalProperties": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "body", "header", "query", "jwt_claim" ] }, "path": { "type": "string" } }, "required": [ "source", "path" ], "additionalProperties": false } }, "identityTransforms": { "type": "object", "additionalProperties": { "type": "string" } }, "autoCreateUsers": { "type": "boolean" }, "allowEmailLink": { "type": "boolean" } }, "required": [ "auth", "identity" ], "additionalProperties": false } }, "defaults": { "type": "object", "additionalProperties": {} }, "widgets": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/WidgetConfig" } }, "pages": { "type": "object", "additionalProperties": { "type": "object", "properties": { "layout": { "$ref": "#/components/schemas/__schema0" }, "data": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] }, { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" } ] } } ] }, "dataSources": { "type": "object", "additionalProperties": { "type": "object", "properties": {}, "additionalProperties": {} } }, "widgets": { "type": "object", "additionalProperties": { "type": "object", "properties": { "widgetComponent": { "type": "string" }, "config": {} }, "required": [ "widgetComponent" ], "additionalProperties": {} } } }, "required": [ "layout" ], "additionalProperties": {} } }, "policies": { "type": "object", "additionalProperties": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": "string" }, "grants": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string" }, "resourceId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "string", "const": "$app_config" } ] }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } }, "attributeFilter": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "value": {} }, "required": [ "operator", "path", "value" ], "additionalProperties": false } } }, "required": [ "resourceType", "resourceId", "actions" ], "additionalProperties": false } } }, "required": [ "grants" ], "additionalProperties": false } }, "defaultPolicy": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "shares": { "type": "object", "properties": { "entityTypes": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "jsonSchemas": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "entities": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "entityType": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "scope": { "type": "string", "const": "all" } }, "required": [ "entityType", "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "entityType": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "scope": { "type": "string", "const": "specific" }, "entityIds": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } } }, "required": [ "entityType", "scope", "entityIds" ], "additionalProperties": false }, { "type": "object", "properties": { "entityType": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "scope": { "type": "string", "const": "filter" }, "attributeFilter": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "value": {} }, "required": [ "operator", "path", "value" ], "additionalProperties": false } } }, "required": [ "entityType", "scope", "attributeFilter" ], "additionalProperties": false } ] } } }, "additionalProperties": false }, "jobs": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobDefinitionV1" } }, "principalConfigSchemas": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "functions": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "dashboards" ], "additionalProperties": {} } }, "additionalProperties": false }, "JsonSchemaCatalogItem": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_definition": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "JSON Schema definition object" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ItemLifecycleStatus" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "source_type": { "type": "string", "enum": [ "shared", "owned", "internal" ], "description": "Origin of a schema item — owned (created by this tenant), shared (received cross-tenant from another tenant), internal (system-managed)." } }, "required": [ "id", "name", "description", "schema_definition", "status", "created_at", "updated_at", "source_type" ], "additionalProperties": false }, "ListSchemasResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JsonSchemaCatalogItem" } } }, "required": [ "data" ], "additionalProperties": false }, "CreateJsonSchemaCatalogItem": { "type": "object" }, "GetSchemaResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JsonSchemaCatalogItem" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateJsonSchemaCatalogItem": { "type": "object" }, "ValidateSchemaDto": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "data": {}, "strip_additional": { "description": "When `false`, validate WITHOUT removing keys absent from the schema's `properties` (the JSON-Schema default of allow/keep). Prototype-pollution keys (`__proto__`/`constructor`/`prototype`) are always dropped regardless. Defaults to `true` (strip), preserving the default-deny behaviour for entity/definition validation. Callers that carry pass-through fields (e.g. job-input evaluation) opt out with `false`.", "type": "boolean" } }, "required": [ "data" ], "additionalProperties": false }, "ValidateSchemaBulkDto": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "items": { "type": "array", "items": {} }, "strip_additional": { "description": "See `strip_additional` on the single-item validate request.", "type": "boolean" } }, "required": [ "items" ], "additionalProperties": false }, "AppConfig": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "app_spec_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "config": { "type": "object", "additionalProperties": {} }, "policy_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "policy_source": { "type": "string", "enum": [ "spec", "operator" ] }, "policy_sync_status": { "type": "string", "enum": [ "pending", "synced", "failed" ] }, "is_enabled": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "app_spec_id", "name", "config", "policy_source", "policy_sync_status", "is_enabled", "created_at", "updated_at" ], "additionalProperties": false }, "GetAppConfigResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppConfig" } }, "required": [ "data" ], "additionalProperties": false }, "UpsertAppConfig": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "config": { "type": "object", "additionalProperties": {} }, "is_enabled": { "type": "boolean" }, "policy_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "policy": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": "string" }, "grants": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string" }, "resourceId": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "string", "const": "$app_config" } ] }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } }, "attributeFilter": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string" }, "path": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "value": {} }, "required": [ "operator", "path", "value" ], "additionalProperties": false } } }, "required": [ "resourceType", "resourceId", "actions" ], "additionalProperties": false } }, "name": { "type": "string", "minLength": 1 } }, "required": [ "grants", "name" ], "additionalProperties": false } }, "additionalProperties": false }, "CreateAppIntegration": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "external_company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string", "minLength": 1 }, "is_enabled": { "default": true, "type": "boolean" }, "config": { "default": {}, "type": "object", "additionalProperties": {} }, "allowed_origins": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(https?:\\/\\/)[A-Za-z0-9._\\-*]+(:\\d{1,5})?$" } } }, "required": [ "external_company_id", "name", "is_enabled", "config", "allowed_origins" ], "additionalProperties": false }, "IssueAppToken": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "name" ], "additionalProperties": false }, "AppToken": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "app_integration_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "token_prefix": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usage_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "app_integration_id", "name", "description", "token_prefix", "status", "expires_at", "last_used_at", "usage_count", "created_at", "updated_at" ], "additionalProperties": false }, "IssueAppTokenResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppToken" }, "raw_token": { "type": "string" } }, "required": [ "data", "raw_token" ], "additionalProperties": false }, "ListAppTokensResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppToken" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "page", "limit", "total", "total_pages" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "UpsertPrincipalConfig": { "type": "object", "properties": { "config": { "default": {}, "type": "object", "additionalProperties": {} } }, "required": [ "config" ], "additionalProperties": false }, "SpecRole": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "label", "description" ], "additionalProperties": false }, "ListSpecRolesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SpecRole" } } }, "required": [ "data" ], "additionalProperties": false }, "AssignSpecPolicy": { "type": "object", "properties": { "policy": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" } }, "required": [ "policy" ], "additionalProperties": false }, "TriggerWorkflow": { "type": "object", "properties": { "workflow_name": { "type": "string", "minLength": 1 }, "workflow_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "trigger": { "type": "string" }, "entity_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "event_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "parent_workflow_run_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "trigger_dedup_key": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "trigger" ], "additionalProperties": false }, "RunStatus": { "type": "string", "enum": [ "pending", "ready", "running", "waiting_for_input", "waiting_for_event", "success", "error", "skipped", "cancelled", "timeout" ] }, "WorkflowRunSummary": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "original_workflow_run_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "attempt_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "context_data": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Workflow execution context data" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/RunStatus" }, "created_at": { "type": "string" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorObject" }, { "type": "null" } ] } }, "required": [ "id", "original_workflow_run_id", "attempt_number", "context_data", "status", "created_at", "started_at", "completed_at", "error" ], "additionalProperties": false }, "GetWorkflowRunResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "original_workflow_run_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "attempt_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "context_data": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Workflow execution context data" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/RunStatus" }, "created_at": { "type": "string" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorObject" }, { "type": "null" } ] }, "job_runs": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "job_runs_truncated": { "type": "boolean" }, "source": { "type": "string", "enum": [ "database", "archive" ] }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunSummary" } } }, "required": [ "id", "original_workflow_run_id", "attempt_number", "context_data", "status", "created_at", "started_at", "completed_at", "error", "job_runs" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "ListWorkflowRunsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunSummary" } } }, "required": [ "data" ], "additionalProperties": false }, "ListJobRunsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "step_id": { "type": "string" }, "workflow_run_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "status": { "$ref": "#/components/schemas/RunStatus" }, "created_at": { "type": "string" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "input": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Job run input data" }, { "type": "null" } ] }, "output": { "anyOf": [ { "type": "object", "additionalProperties": {}, "description": "Job run output data" }, { "type": "null" } ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorObject" }, { "type": "null" } ] } }, "required": [ "id", "step_id", "workflow_run_id", "status", "created_at", "started_at", "completed_at", "input", "output", "error" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "ListActionRunsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "job_run_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "workflow_run_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "step_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/RunStatus" }, "created_at": { "type": "string" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorObject" }, { "type": "null" } ] }, "output": {} }, "required": [ "id", "name", "job_run_id", "workflow_run_id", "step_id", "status", "created_at", "started_at", "completed_at", "error" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "CreateWorkflowScheduleDto": { "type": "object", "properties": { "workflow_name": { "type": "string", "minLength": 1 }, "trigger": { "type": "string" } }, "required": [ "workflow_name", "trigger" ], "additionalProperties": false }, "CreateScheduleResponse": { "type": "object", "properties": { "trigger": { "type": "string" }, "cron": { "type": "string" }, "delay": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "trigger", "cron", "created_at" ], "additionalProperties": false }, "ListSchedulesResponse": { "type": "array", "items": { "type": "object", "properties": { "trigger": { "type": "string" }, "cron": { "type": "string" }, "delay": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "trigger", "cron", "created_at" ], "additionalProperties": false } }, "DeleteWorkflowScheduleDto": { "type": "object", "properties": { "workflow_name": { "type": "string", "minLength": 1 }, "trigger": { "type": "string" } }, "required": [ "workflow_name", "trigger" ], "additionalProperties": false }, "ActivateWorkflow": { "default": { "env": {} }, "type": "object", "properties": { "env": { "description": "Environment variables — null values must be set as tenant-specific config", "type": "object", "additionalProperties": {} }, "regenerate_secrets": { "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ] }, "policy_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] }, "policy": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "grants": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string" }, "resourceId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } } }, "required": [ "resourceType", "resourceId", "actions" ], "additionalProperties": false } } }, "required": [ "name", "grants" ], "additionalProperties": false } }, "additionalProperties": false }, "ActivatedWorkflowTrigger": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "definition_id": { "type": "string" }, "type": { "type": "string" }, "webhook_url": { "type": "string" }, "schedule": { "type": "string" }, "source": { "type": "object", "properties": { "entity_type_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "event_action": { "type": "string" } }, "required": [ "entity_type_id", "event_action" ], "additionalProperties": false }, "has_secret": { "type": "boolean" }, "config_status": { "type": "string" }, "created_at": { "type": "string" }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secret_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rotated": { "type": "boolean" } }, "required": [ "id", "definition_id", "type", "has_secret", "config_status", "created_at" ], "additionalProperties": false }, "ActivatedWorkflowPolicy": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "operator_id", "operator_inline", "definition", "none" ] } }, "required": [ "id", "name", "source" ], "additionalProperties": false }, "ActivateWorkflowResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workflow" }, "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/ActivatedWorkflowTrigger" } }, "policy": { "anyOf": [ { "$ref": "#/components/schemas/ActivatedWorkflowPolicy" }, { "type": "null" } ] } }, "required": [ "data", "triggers", "policy" ], "additionalProperties": false }, "WorkflowTrigger": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "definition_id": { "type": "string" }, "type": { "type": "string" }, "webhook_url": { "type": "string" }, "schedule": { "type": "string" }, "source": { "type": "object", "properties": { "entity_type_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "event_action": { "type": "string" } }, "required": [ "entity_type_id", "event_action" ], "additionalProperties": false }, "has_secret": { "type": "boolean" }, "config_status": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "definition_id", "type", "has_secret", "config_status", "created_at" ], "additionalProperties": false }, "ListWorkflowTriggersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowTrigger" } } }, "required": [ "data" ], "additionalProperties": false }, "GenerateWebhookSecretResponse": { "type": "object", "properties": { "message": { "type": "string" }, "secret": { "type": "string" }, "secret_id": { "type": "string" } }, "required": [ "message", "secret", "secret_id" ], "additionalProperties": false }, "CreateAccessUser": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 8 }, "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "foreign_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role_ids": { "default": [], "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } } }, "required": [ "email", "role_ids" ], "additionalProperties": false }, "UpdateAccessUser": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "foreign_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active_in_tenant": { "type": "boolean" } }, "additionalProperties": false }, "CreateRoleAssignment": { "type": "object", "properties": { "auth_user_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "policy_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "role_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "required": [ "auth_user_id" ], "additionalProperties": false }, "Policy": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "created_at", "updated_at" ], "additionalProperties": false }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total_pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "page", "limit", "total", "total_pages" ], "additionalProperties": false }, "ListPoliciesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ], "additionalProperties": false }, "CreatePolicy": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "grants": { "type": "array", "items": { "type": "object", "properties": { "resource_type": { "type": "string" }, "resource_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } } }, "required": [ "resource_type", "resource_id", "actions" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false }, "PolicyWithGrants": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyGrant" } } }, "required": [ "id", "name", "description", "created_at", "updated_at", "grants" ], "additionalProperties": false }, "PolicyGrant": { "type": "object", "properties": { "resource_type": { "type": "string" }, "resource_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "resource_type", "resource_id", "actions", "id", "is_active", "created_at" ], "additionalProperties": false }, "GetPolicyResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PolicyWithGrants" } }, "required": [ "data" ], "additionalProperties": false }, "UpdatePolicy": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "ListPolicyGrantsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyGrant" } } }, "required": [ "data" ], "additionalProperties": false }, "AddPolicyGrants": { "type": "object", "properties": { "grants": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "resource_type": { "type": "string" }, "resource_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } } }, "required": [ "resource_type", "resource_id", "actions" ], "additionalProperties": false } }, "partial_success": { "type": "boolean" } }, "required": [ "grants" ], "additionalProperties": false }, "PartialGrantResultResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PartialGrantResult" } }, "required": [ "data" ], "additionalProperties": false }, "PartialGrantResult": { "type": "object", "properties": { "accepted": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyGrant" } }, "rejected": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyGrantRejection" } } }, "required": [ "accepted", "rejected" ], "additionalProperties": false }, "PolicyGrantRejection": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "code": { "type": "string" }, "message": { "type": "string" }, "input": { "type": "object", "properties": { "resource_type": { "type": "string" }, "resource_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } } }, "required": [ "resource_type", "resource_id", "actions" ], "additionalProperties": false } }, "required": [ "index", "code", "message", "input" ], "additionalProperties": false }, "AddPolicyGrantsResponse": { "anyOf": [ { "$ref": "#/components/schemas/ListPolicyGrantsResponse" }, { "$ref": "#/components/schemas/PartialGrantResultResponse" } ] }, "ReplacePolicyGrants": { "type": "object", "properties": { "grants": { "type": "array", "items": { "type": "object", "properties": { "resource_type": { "type": "string" }, "resource_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } } }, "required": [ "resource_type", "resource_id", "actions" ], "additionalProperties": false } } }, "required": [ "grants" ], "additionalProperties": false }, "CreateGrant": { "type": "object", "properties": { "grantee_kind": { "type": "string", "enum": [ "user", "team", "policy" ] }, "grantee_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } }, "is_active": { "default": true, "type": "boolean" } }, "required": [ "grantee_kind", "grantee_id", "resource_type", "resource_id", "actions", "is_active" ], "additionalProperties": false }, "TenantCreateExternalUser": { "type": "object", "properties": { "external_company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "external_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "first_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "last_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "external_data": { "type": "object", "additionalProperties": {} }, "link_existing_email": { "type": "boolean" } }, "required": [ "external_company_id", "external_id", "email" ], "additionalProperties": false }, "TenantUpdateExternalUser": { "type": "object", "properties": { "external_data": { "type": "object", "additionalProperties": {} }, "is_active": { "type": "boolean" } }, "additionalProperties": false }, "CreateAccessApiToken": { "type": "object", "properties": { "user_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "policy_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, { "type": "null" } ] } }, "required": [ "user_id", "name" ], "additionalProperties": false }, "PutApiTokenPolicy": { "type": "object", "properties": { "policy_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "required": [ "policy_id" ], "additionalProperties": false }, "ManifestChild": { "type": "object", "properties": { "resource_type": { "type": "string", "enum": [ "entity_type", "entity", "relationship_rule", "json_schema", "workflow_definition", "job_definition", "app_spec" ] }, "resource_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "actions": { "default": [ "read" ], "minItems": 1, "type": "array", "items": { "type": "string", "const": "read" } } }, "required": [ "resource_type", "resource_id", "actions" ], "additionalProperties": false }, "CreateManifest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Human-readable manifest name; unique within the caller's tenant." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "children": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/ManifestChild" } } }, "required": [ "name", "children" ], "additionalProperties": false }, "UpdateManifest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ManifestChild" } } }, "additionalProperties": false }, "CreatePublication": { "type": "object", "properties": { "grantee_tenant_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" } }, "required": [ "grantee_tenant_id" ], "additionalProperties": false }, "UpdatePublication": { "type": "object", "properties": { "is_active": { "type": "boolean" } }, "required": [ "is_active" ], "additionalProperties": false }, "SetSecretRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "scope": { "default": "tenant", "type": "string", "enum": [ "tenant", "company", "team", "user", "app" ] }, "scopeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "name", "value", "scope" ], "additionalProperties": false }, "ListSecretsResponse": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "tenant", "company", "team", "user", "app" ] }, "scopeId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "scope", "name" ], "additionalProperties": false } }, "ListSecretsResponseEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ListSecretsResponse" } }, "required": [ "data" ], "additionalProperties": false }, "EffectivePermissionEntry": { "type": "object", "properties": { "resource_type": { "$ref": "#/components/schemas/PermissionResource" }, "action": { "type": "string", "enum": [ "create", "read", "update", "delete" ] } }, "required": [ "resource_type", "action" ], "additionalProperties": false }, "PermissionResource": { "type": "string", "enum": [ "entity_type", "entity", "json_schema", "workflow_definition", "workflow_run", "job_definition", "job_run", "action_run", "api_token", "workflow_secret", "workflow_token", "user", "team", "role", "tenant_system_item_enablement", "relationship_rule", "relationship_instance", "app_spec", "app_config", "app_integration", "app_token", "principal_config", "external_company", "external_user", "access_policy", "secret", "workflow_config" ] }, "EffectivePermissions": { "type": "object", "properties": { "is_super_admin": { "type": "boolean" }, "is_tenant_admin": { "type": "boolean" }, "allowed": { "type": "array", "items": { "$ref": "#/components/schemas/EffectivePermissionEntry" } } }, "required": [ "is_super_admin", "is_tenant_admin", "allowed" ], "additionalProperties": false }, "TokenExchange": { "type": "object", "properties": { "grant_type": { "type": "string", "const": "client_credentials" }, "client_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "client_secret": { "type": "string", "minLength": 1 }, "scope": { "type": "string" } }, "required": [ "client_id", "client_secret" ], "additionalProperties": false }, "TokenExchangeResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "access_token", "token_type", "expires_in" ], "additionalProperties": false }, "CreateApiToken": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "permissions": { "type": "object", "additionalProperties": {}, "description": "Token permission map" }, "expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "name" ], "additionalProperties": false }, "CreateApiTokenResponse": { "type": "object", "properties": { "client_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "client_secret": { "type": "string" }, "name": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "client_id", "client_secret", "name", "expires_at" ], "additionalProperties": false }, "CreateApiTokenResponseEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateApiTokenResponse" } }, "required": [ "data" ], "additionalProperties": false }, "ListApiTokensResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "UUID format (PostgreSQL compatible)" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "token_prefix": { "type": "string" }, "permissions": { "type": "object", "additionalProperties": {}, "description": "Token permission map" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "description", "token_prefix", "permissions", "expires_at", "last_used_at", "status", "created_at" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } }, "responses": { "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServiceUnavailable": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic", "description": "Basic authentication with base64 encoded client_id:client_secret" } } } }