{ "openapi": "3.1.0", "info": { "title": "Solarius Connector API", "version": "1.0.0", "description": "Organization-scoped product connections, custom integration context, and webhook delivery." }, "servers": [ { "url": "{origin}", "variables": { "origin": { "default": "https://connector.example.com", "description": "Replace with the API origin displayed in Connector Developer settings; the example origin is not a production service." } } } ], "paths": { "/api/v1/connector/organizations/{organization_id}/connections": { "get": { "operationId": "api_connections_get_list_connections", "summary": "List connections", "description": "Lists connections visible to the principal.", "tags": ["connections"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["connections:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Visible records.", "items": { "$ref": "#/components/schemas/Connection" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"], "description": "Continuation token or null after the final page." } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "pagination", "request_id"], "additionalProperties": false, "description": "a `data` array of `Connection` records, `pagination.next_cursor`, and `request_id`" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } }, "post": { "operationId": "api_connections_post_create_a_connection", "summary": "Create a connection", "description": "Creates a draft relationship with immutable endpoint identities. Both endpoints must belong to the owning organization. Unsupported Status endpoints return `422 product_unavailable`. Creation grants no exchange; add and approve [directional grants](api-grants.md).", "tags": ["connections"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["connections:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Connection" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Connection`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionCreate" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}": { "get": { "operationId": "api_connections_get_read_a_connection", "summary": "Read a connection", "description": "Returns participant identities, the active grant generation, health, and synchronization time.", "tags": ["connections"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["connections:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Connection" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Connection`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "api_connections_delete_delete_a_connection", "summary": "Delete a connection", "description": "Deletes a revoked connection after its transport dependencies are resolved. Active grants or unresolved deliveries return `409 connection_in_use`. Resolve the listed dependencies; use native product retirement for hosted capacity or protected routes.", "tags": ["connections"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["connections:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." } ], "responses": { "204": { "description": "Removed", "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/activate": { "post": { "operationId": "api_connections_post_activate_a_connection", "summary": "Activate a connection", "description": "Activates a draft connection and its approved grants. Poll the returned operation, then read the connection. Activation requires both endpoint approvals for every selected grant. Pause and revocation do not cancel accepted native product work. Invalid lifecycle transitions return `409 invalid_state`.", "tags": ["connections"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["connections:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/pause": { "post": { "operationId": "api_connections_post_pause_a_connection", "summary": "Pause a connection", "description": "Stops subsequent exchange after the operation acknowledges Paused. Poll the returned operation, then read the connection. Activation requires both endpoint approvals for every selected grant. Pause and revocation do not cancel accepted native product work. Invalid lifecycle transitions return `409 invalid_state`.", "tags": ["connections"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["connections:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/resume": { "post": { "operationId": "api_connections_post_resume_a_connection", "summary": "Resume a connection", "description": "Rechecks active grants and refreshes permitted present state. Poll the returned operation, then read the connection. Activation requires both endpoint approvals for every selected grant. Pause and revocation do not cancel accepted native product work. Invalid lifecycle transitions return `409 invalid_state`.", "tags": ["connections"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["connections:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/revoke": { "post": { "operationId": "api_connections_post_revoke_a_connection", "summary": "Revoke a connection", "description": "Revokes subsequent exchange and all connection grants; fresh approval is required to reconnect. Poll the returned operation, then read the connection. Activation requires both endpoint approvals for every selected grant. Pause and revocation do not cancel accepted native product work. Invalid lifecycle transitions return `409 invalid_state`.", "tags": ["connections"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["connections:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grants": { "get": { "operationId": "api_grants_get_list_grants", "summary": "List grants", "description": "Lists directional selections and their approval and activation states.", "tags": ["grants"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["grants:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Visible records.", "items": { "$ref": "#/components/schemas/Grant" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"], "description": "Continuation token or null after the final page." } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "pagination", "request_id"], "additionalProperties": false, "description": "a `data` array of `Grant` records, `pagination.next_cursor`, and `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } }, "post": { "operationId": "api_grants_post_propose_a_grant", "summary": "Propose a grant", "description": "Creates an immutable selection for endpoint review. Use the connection ETag. The source and destination must differ. Unavailable scopes, invalid category directions, and label keys outside the source permission return `422 invalid_selection`. A replacement leaves the active grant unchanged until activation.", "tags": ["grants"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["grants:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Grant" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Grant`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCreate" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grants/{grant_id}": { "get": { "operationId": "api_grants_get_read_a_grant", "summary": "Read a grant", "description": "Returns the exact selection, approvals, revision, and state.", "tags": ["grants"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["grants:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Grant" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Grant`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grants/{grant_id}/decisions": { "post": { "operationId": "api_grants_post_approve_or_reject_a_grant", "summary": "Approve or reject a grant", "description": "Records one endpoint decision for the reviewed grant revision. Requires native product administrator authority for a native side, or Connector Administrator authority over a custom side. An Integration Developer key cannot approve native product access. Rejected grants cannot activate; propose a corrected selection.", "tags": ["grants"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["grants:approve"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Grant" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Grant`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantDecision" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grants/{grant_id}/activate": { "post": { "operationId": "api_grants_post_activate_a_replacement_grant", "summary": "Activate a replacement grant", "description": "Replaces the active directional selection with an approved revision. Use the grant ETag. Both required approvals must match the revision or the request returns `409 approval_required`. Initial draft connections use [connection activation](api-connections.md#activate-a-connection). Read the connection after operation success to confirm the active grant generation.", "tags": ["grants"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["grants:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grants/{grant_id}/revoke": { "post": { "operationId": "api_grants_post_revoke_a_grant", "summary": "Revoke a grant", "description": "Stops subsequent exchange through the selected directional grant. Poll the operation and confirm `revoked` on the grant. Received copies retain destination access and retention rules; revocation does not recall them.", "tags": ["grants"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["grants:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/resources": { "get": { "operationId": "api_resources_get_list_shared_resources", "summary": "List shared resources", "description": "Lists the inventory and permitted summaries visible through active grants. The first request fixes a snapshot. Subsequent pages retain its snapshot ID and grant generation. Cursors expire after 600 seconds (`410 cursor_expired`); a scope change returns `409 scope_changed`. Restart from the first page and commit only a complete result. Inventory does not establish active protection.", "tags": ["resources"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["resources:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Visible records.", "items": { "$ref": "#/components/schemas/Resource" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"], "description": "Continuation token or null after the final page." } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 }, "snapshot_id": { "type": "string", "description": "Consistent inventory snapshot.", "minLength": 1, "maxLength": 200 }, "grant_revision": { "type": "integer", "description": "Active grant generation used by the snapshot.", "minimum": 1 } }, "required": [ "data", "pagination", "request_id", "snapshot_id", "grant_revision" ], "additionalProperties": false, "description": "`Resource` records with `snapshot_id`, `grant_revision`, pagination, and request correlation" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/resources/{resource_key}": { "get": { "operationId": "api_resources_get_read_a_shared_resource", "summary": "Read a shared resource", "description": "Returns the permitted present summary of a qualified source resource. Percent-encode the opaque resource key as one path segment. Removed or no-longer-visible resources return `404 resource_not_found`; use source history or removal events to investigate.", "tags": ["resources"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["resources:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "resource_key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Resource" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Resource`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/mappings": { "get": { "operationId": "api_mappings_get_list_mappings", "summary": "List mappings", "description": "Lists confirmed relationships and stale references for the connection.", "tags": ["mappings"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["mappings:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Visible records.", "items": { "$ref": "#/components/schemas/Mapping" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"], "description": "Continuation token or null after the final page." } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "pagination", "request_id"], "additionalProperties": false, "description": "a `data` array of `Mapping` records, `pagination.next_cursor`, and `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } }, "post": { "operationId": "api_mappings_post_create_a_mapping", "summary": "Create a mapping", "description": "Confirms a relationship between resource keys on opposite endpoints. Both resources must be visible under the current grant and the caller must have destination mapping authority. Missing resources return `404`; unsupported pairs return `422 incompatible_resources`; an existing pair returns `409 mapping_exists`. Creation does not enroll an agent or admit a traffic route.", "tags": ["mappings"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["mappings:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Mapping" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Mapping`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MappingCreate" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/mappings/{mapping_id}": { "get": { "operationId": "api_mappings_get_read_a_mapping", "summary": "Read a mapping", "description": "Returns both qualified identities, the reason, and stale-reference state.", "tags": ["mappings"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["mappings:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "mapping_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Mapping" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Mapping`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "api_mappings_delete_delete_a_mapping", "summary": "Delete a mapping", "description": "Removes the relationship without deleting either referenced resource. Previously delivered observations remain historical records. A replacement workload requires a separately reviewed mapping for its replacement resource key.", "tags": ["mappings"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["mappings:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "mapping_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." } ], "responses": { "204": { "description": "Removed", "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" } } } }, "/api/v1/connector/organizations/{organization_id}/integrations": { "get": { "operationId": "api_integrations_get_list_integrations", "summary": "List integrations", "description": "Lists customer-owned registrations visible to the principal.", "tags": ["integrations"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["integrations:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Visible records.", "items": { "$ref": "#/components/schemas/Integration" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"], "description": "Continuation token or null after the final page." } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "pagination", "request_id"], "additionalProperties": false, "description": "a `data` array of `Integration` records, `pagination.next_cursor`, and `request_id`" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } }, "post": { "operationId": "api_integrations_post_register_an_integration", "summary": "Register an integration", "description": "Creates an enabled registration without connection grants or API keys. Registration requires Connector Administrator authority or a delegated registration grant. Create keys through [service-account access](api-authentication.md#create-a-service-account-and-key). A registration is not a native product approval.", "tags": ["integrations"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["integrations:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Integration`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationCreate" } } } } } }, "/api/v1/connector/organizations/{organization_id}/integrations/{integration_id}": { "get": { "operationId": "api_integrations_get_read_an_integration", "summary": "Read an integration", "description": "Returns registration metadata, enabled state, and revision.", "tags": ["integrations"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["integrations:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Integration`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "api_integrations_patch_update_an_integration", "summary": "Update an integration", "description": "Updates metadata or suspends the integration identity. Omitted fields retain their values. An empty update returns `422 empty_update`. Disabling blocks subsequent exchanges and custom record writes; existing copies and native operations remain. Re-enable and synchronize before resuming the consumer.", "tags": ["integrations"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["integrations:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Integration`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationPatch" } } } } }, "delete": { "operationId": "api_integrations_delete_delete_an_integration", "summary": "Delete an integration", "description": "Deletes a disabled registration after its dependencies are removed. Enabled registrations, retained external records, or connection references return `409 integration_in_use`. Retire connections and records first; revoke its service-account keys separately.", "tags": ["integrations"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["integrations:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." } ], "responses": { "204": { "description": "Removed", "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" } } } }, "/api/v1/connector/organizations/{organization_id}/integrations/{integration_id}/records": { "get": { "operationId": "api_records_get_list_external_records", "summary": "List external records", "description": "Lists records owned by this custom integration.", "tags": ["records"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["resources:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Visible records.", "items": { "$ref": "#/components/schemas/ExternalRecord" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"], "description": "Continuation token or null after the final page." } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "pagination", "request_id"], "additionalProperties": false, "description": "a `data` array of `ExternalRecord` records, `pagination.next_cursor`, and `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } } }, "/api/v1/connector/organizations/{organization_id}/integrations/{integration_id}/records/{external_id}": { "get": { "operationId": "api_records_get_read_an_external_record", "summary": "Read an external record", "description": "Returns the external record, assigned resource key, and current ETag.", "tags": ["records"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["resources:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExternalRecord" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `ExternalRecord`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } }, "put": { "operationId": "api_records_put_create_or_replace_an_external_record", "summary": "Create or replace an external record", "description": "Creates or replaces a custom service, deployment, or ticket summary. Use `If-None-Match: *` to create and `If-Match` with the record ETag to replace. Creation returns `201`; replacement returns `200`. Missing preconditions return `428`; stale or conflicting preconditions return `412`. External IDs match `[A-Za-z0-9_-]{1,128}`. Omitted labels become `{}`; other fields are required. Kind cannot change. Visibility in native product context additionally requires an active `external_context` grant and explicit mapping. Connector assigns revisions; callers cannot overwrite a native product record.", "tags": ["records"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["records:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required to replace an existing record." }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Use * to create a record only if absent." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExternalRecord" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `ExternalRecord`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExternalRecord" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `ExternalRecord`, plus `request_id`" } } } }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalRecordWrite" } } } } }, "delete": { "operationId": "api_records_delete_delete_an_external_record", "summary": "Delete an external record", "description": "Removes present custom context and marks its mappings stale. Emits `external.record.removed` for authorized receivers. Journal history and previously exported copies retain their separate retention. A mapping is not silently rebound if an external ID is recreated; review a replacement resource key.", "tags": ["records"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["records:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." } ], "responses": { "204": { "description": "Removed", "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" } } } }, "/api/v1/connector/organizations/{organization_id}/events": { "get": { "operationId": "api_events_get_list_events", "summary": "List events", "description": "Lists authorized events still retained in the 7-day transport journal. Authorization is evaluated at read time. Event data can be redacted after a grant reduction; full removal suppresses visibility. Events are observations, not proof of native action completion.", "tags": ["events"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["events:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." }, { "name": "connection_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit to one allowed connection." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Event category.", "enum": [ "inventory.upserted", "inventory.removed", "security.summary.updated", "external.record.updated", "external.record.removed", "connection.state.changed", "mapping.changed", "operation.completed", "subscription.test" ] }, "description": "Limit to one event type." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Include events recorded at or after this UTC time; omitted starts at retained history." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Visible records.", "items": { "$ref": "#/components/schemas/Event" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"], "description": "Continuation token or null after the final page." } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "pagination", "request_id"], "additionalProperties": false, "description": "a `data` array of `Event` records, `pagination.next_cursor`, and `request_id`" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } } }, "/api/v1/connector/organizations/{organization_id}/events/{event_id}": { "get": { "operationId": "api_events_get_read_an_event", "summary": "Read an event", "description": "Returns a retained event under present authorization. An expired journal reference returns `410 event_expired`. An inaccessible reference returns `404`. Re-read current resources before making a dependent change.", "tags": ["events"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["events:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Event" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Event`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } } }, "/api/v1/connector/organizations/{organization_id}/subscriptions": { "get": { "operationId": "api_subscriptions_get_list_subscriptions", "summary": "List subscriptions", "description": "Lists visible subscriptions without secret material or full destination URLs.", "tags": ["subscriptions"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["subscriptions:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Visible records.", "items": { "$ref": "#/components/schemas/Subscription" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"], "description": "Continuation token or null after the final page." } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "pagination", "request_id"], "additionalProperties": false, "description": "a `data` array of `Subscription` records, `pagination.next_cursor`, and `request_id`" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } }, "post": { "operationId": "api_subscriptions_post_create_a_subscription", "summary": "Create a subscription", "description": "Creates a disabled receiver and reveals its initial signing secret once. An enabled initial value returns `422 test_required`. URL validation rejects credentials, private or local addresses, unsupported schemes, and redirects. Test the saved URL before enabling. If the one-time secret response is lost, read the subscription ID from its idempotent retry, rotate its secret, and revoke the unseen version; replay never repeats secret plaintext.", "tags": ["subscriptions"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["subscriptions:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubscriptionCreated" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `SubscriptionCreated`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreate" } } } } } }, "/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}": { "get": { "operationId": "api_subscriptions_get_read_a_subscription", "summary": "Read a subscription", "description": "Returns saved filters, destination host, enabled state, and test status.", "tags": ["subscriptions"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["subscriptions:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Subscription" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Subscription`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "api_subscriptions_patch_update_a_subscription", "summary": "Update a subscription", "description": "Updates receiver configuration or enabled state. Omitted fields remain unchanged. URL or filter changes disable delivery and reset `test_state` to `not_tested`; do not combine them with `enabled: true`. Enabling before a delivered test returns `409 test_required`. Disabling stops subsequent scheduling; in-flight attempts can already have reached the receiver.", "tags": ["subscriptions"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["subscriptions:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Subscription" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Subscription`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPatch" } } } } }, "delete": { "operationId": "api_subscriptions_delete_delete_a_subscription", "summary": "Delete a subscription", "description": "Deletes a disabled subscription after deliveries finish or are suppressed. Enabled delivery or unresolved attempts return `409 subscription_in_use`. Disable, inspect deliveries, and resolve their outcomes before deletion.", "tags": ["subscriptions"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["subscriptions:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." } ], "responses": { "204": { "description": "Removed", "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" } } } }, "/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/test": { "post": { "operationId": "api_subscriptions_post_test_a_subscription", "summary": "Test a subscription", "description": "Sends a signed synthetic subscription.test event while normal delivery is disabled. The test uses the saved URL and active signing secret. Poll the operation, then read the subscription for `test_state: delivered`. An HTTP acknowledgement proves receiver admission, not downstream processing.", "tags": ["subscriptions"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["subscriptions:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/signing-secrets": { "post": { "operationId": "api_subscriptions_post_create_a_signing_secret", "summary": "Create a signing secret", "description": "Creates and activates a replacement signing version, revealed once. Use the subscription ETag. At most 2 versions can be active; another returns `409 secret_limit`. New attempts use the replacement. Install it in the receiver, send a test, confirm its secret ID in receiver logs, then revoke the previous version. Keep the previous verifier only until that check succeeds.", "tags": ["subscriptions"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["subscriptions:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SigningSecret" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `SigningSecret`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } }, "get": { "operationId": "api_subscriptions_get_list_signing_secret_versions", "summary": "List signing secret versions", "description": "Lists version IDs and creation times without plaintext.", "tags": ["subscriptions"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["subscriptions:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Active secret metadata.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Version ID.", "minLength": 1, "maxLength": 200 }, "created_at": { "type": "string", "description": "Creation time.", "format": "date-time" } }, "required": ["id", "created_at"], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"] } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "pagination", "request_id"], "additionalProperties": false } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } } }, "/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/signing-secrets/{secret_id}": { "delete": { "operationId": "api_subscriptions_delete_revoke_a_signing_secret", "summary": "Revoke a signing secret", "description": "Revokes the selected signing version. Use the subscription ETag. Removing the last active version while enabled returns `409 secret_in_use`. For a compromised last secret, disable delivery first, then revoke it. Remove the version from the receiver verifier as well.", "tags": ["subscriptions"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["subscriptions:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "secret_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." } ], "responses": { "204": { "description": "Removed", "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" } } } }, "/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/deliveries": { "get": { "operationId": "api_deliveries_get_list_deliveries", "summary": "List deliveries", "description": "Lists delivery states, stable event IDs, and attempt outcomes.", "tags": ["deliveries"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["deliveries:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Number of records; bounds are inclusive." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque continuation; preserve the original filters." }, { "name": "event_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter one stable event identity." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "description": "Delivery state.", "enum": [ "queued", "retrying", "delivered", "failed", "suppressed" ] }, "description": "Filter one state." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Visible records.", "items": { "$ref": "#/components/schemas/Delivery" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": ["string", "null"], "description": "Continuation token or null after the final page." } }, "required": ["next_cursor"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "pagination", "request_id"], "additionalProperties": false, "description": "a `data` array of `Delivery` records, `pagination.next_cursor`, and `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" } } } }, "/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/deliveries/{delivery_id}": { "get": { "operationId": "api_deliveries_get_read_a_delivery", "summary": "Read a delivery", "description": "Returns attempts and the last HTTP or transport result. `delivered` means the receiver acknowledged receipt. It does not mean a ticket, deployment, or native response completed.", "tags": ["deliveries"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["deliveries:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Delivery" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Delivery`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/api/v1/connector/organizations/{organization_id}/subscriptions/{subscription_id}/deliveries/{delivery_id}/replay": { "post": { "operationId": "api_deliveries_post_replay_a_delivery", "summary": "Replay a delivery", "description": "Starts a delivery window for the same event under present authorization. Requires an enabled subscription and active connection. A paused or revoked path returns `409 connection_inactive`; an expired event returns `410 event_expired`. Replays use a fresh timestamp and active signing version. Unchanged event identity requires receiver deduplication. Replay is not a way to restore removed grants.", "tags": ["deliveries"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["deliveries:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "410": { "$ref": "#/components/responses/410" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/synchronizations": { "post": { "operationId": "api_operations_post_synchronize_a_connection", "summary": "Synchronize a connection", "description": "Refreshes permitted present state for every active direction. Requires an active connection; otherwise returns `409 connection_inactive`. Success includes all selected directions. A partial refresh returns a failed result with affected resource keys; inspect source references before repeating the task. Synchronization does not reconstruct expired event history.", "tags": ["operations"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["sync:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/v1/connector/organizations/{organization_id}/operations/{operation_id}": { "get": { "operationId": "api_operations_get_read_an_operation", "summary": "Read an operation", "description": "Returns acknowledged progress, result references, and recovery detail. `reconciling` means the outcome is unknown. Keep the original ID and restore its connection before submitting replacement work. A terminal failure does not roll back completed source effects.", "tags": ["operations"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["operations:read"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." } ], "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Operation" }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["data", "request_id"], "additionalProperties": false, "description": "`data` as `Operation`, plus `request_id`" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" } } } }, "/api/v1/connector/organizations/{organization_id}/operations/{operation_id}/cancel": { "post": { "operationId": "api_operations_post_cancel_an_operation", "summary": "Cancel an operation", "description": "Requests cancellation of uncommitted Connector work. Requires `cancelable: true`; otherwise returns `409 not_cancelable`. Poll to a terminal result. Cancellation does not undo delivered copies or cancel linked native product operations.", "tags": ["operations"], "security": [ { "ConnectorKey": [] } ], "x-required-scopes": ["connections:write"], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Organization that owns the connection." }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "ID returned by the corresponding creation or list operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ETag from a current read of the resource being changed." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Organization-scoped retry identity retained for 24 hours." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Operation to poll.", "minLength": 1, "maxLength": 200 } }, "required": ["id"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Request correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["operation", "request_id"], "additionalProperties": false, "description": "`operation.id` for [operation polling](api-operations.md#read-an-operation) and `request_id`; acceptance does not establish completion" } } }, "headers": { "ETag": { "description": "Opaque revision precondition.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "412": { "$ref": "#/components/responses/412" }, "428": { "$ref": "#/components/responses/428" }, "413": { "description": "Request body exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } } }, "components": { "securitySchemes": { "ConnectorKey": { "type": "http", "scheme": "bearer", "description": "Connector service-account key; x-required-scopes lists operation scopes." } }, "schemas": { "Endpoint": { "type": "object", "properties": { "side": { "type": "string", "description": "Stable side within this connection.", "enum": ["a", "b"] }, "product": { "type": "string", "description": "Participating product or custom registration.", "enum": ["infra", "guard", "custom"] }, "organization_id": { "type": "string", "description": "Product organization; must belong to the owning Solarius organization.", "minLength": 1, "maxLength": 200 }, "installation_id": { "type": "string", "description": "Required for Infra or Guard; rejected for a custom endpoint.", "minLength": 1, "maxLength": 200 }, "integration_id": { "type": "string", "description": "Required for custom; rejected for Infra or Guard.", "minLength": 1, "maxLength": 200 } }, "required": ["side", "product", "organization_id"], "additionalProperties": false, "oneOf": [ { "properties": { "product": { "enum": ["infra", "guard"] } }, "required": ["installation_id"], "not": { "required": ["integration_id"] } }, { "properties": { "product": { "const": "custom" } }, "required": ["integration_id"], "not": { "required": ["installation_id"] } } ] }, "ConnectionCreate": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name; renaming preserves identity.", "minLength": 1, "maxLength": 120 }, "endpoints": { "type": "array", "description": "Exactly one a endpoint and one b endpoint; identities are immutable.", "items": { "$ref": "#/components/schemas/Endpoint" }, "minItems": 2, "maxItems": 2 } }, "required": ["name", "endpoints"], "additionalProperties": false }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "description": "Connection identity.", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "description": "Display name.", "minLength": 1, "maxLength": 120 }, "revision": { "type": "integer", "description": "Configuration revision.", "minimum": 1 }, "state": { "type": "string", "description": "Configuration and observed health.", "enum": [ "draft", "pending_approval", "connecting", "connected", "degraded", "disconnected", "paused", "revoked" ] }, "active_grant_revision": { "type": "integer", "description": "Combined active grant generation; 0 before initial activation.", "minimum": 0 }, "endpoints": { "type": "array", "description": "Immutable participant identities.", "items": { "$ref": "#/components/schemas/Endpoint" }, "minItems": 2, "maxItems": 2 }, "last_synchronized_at": { "type": ["string", "null"], "format": "date-time", "description": "Last complete synchronization; null before success." } }, "required": [ "id", "name", "revision", "state", "active_grant_revision", "endpoints", "last_synchronized_at" ], "additionalProperties": false }, "GrantCreate": { "type": "object", "properties": { "source": { "type": "string", "description": "Source endpoint side.", "enum": ["a", "b"] }, "destination": { "type": "string", "description": "Other endpoint side; must differ from source.", "enum": ["a", "b"] }, "source_scope_ids": { "type": "array", "description": "Explicit source projects, groups, or custom integration ID; no wildcard.", "items": { "type": "string", "description": "Scope identity.", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100, "uniqueItems": true }, "destination_scope_id": { "type": "string", "description": "Receiving project, asset group, or integration ID.", "minLength": 1, "maxLength": 200 }, "categories": { "type": "array", "description": "Nonempty categories supported by this direction.", "items": { "type": "string", "description": "Information category.", "enum": [ "resource_inventory", "operational_state", "security_summaries", "external_context" ] }, "minItems": 1, "uniqueItems": true }, "label_keys": { "type": "array", "description": "Inventory labels permitted to cross the boundary; omitted shares no labels.", "items": { "type": "string", "description": "Exact key.", "minLength": 1, "maxLength": 64 }, "maxItems": 20, "uniqueItems": true, "default": [] } }, "required": [ "source", "destination", "source_scope_ids", "destination_scope_id", "categories" ], "additionalProperties": false }, "Grant": { "type": "object", "properties": { "id": { "type": "string", "description": "Grant identity.", "minLength": 1, "maxLength": 200 }, "revision": { "type": "integer", "description": "Immutable reviewed revision.", "minimum": 1 }, "state": { "type": "string", "description": "Approval and activation state.", "enum": [ "pending_approval", "approved", "active", "rejected", "superseded", "revoked" ] }, "selection": { "$ref": "#/components/schemas/GrantCreate" }, "approved_sides": { "type": "array", "description": "Sides that approved this exact selection.", "items": { "type": "string", "description": "Endpoint side.", "enum": ["a", "b"] }, "uniqueItems": true } }, "required": ["id", "revision", "state", "selection", "approved_sides"], "additionalProperties": false }, "Reason": { "type": "object", "properties": { "reason": { "type": "string", "description": "Audited reason; empty values are rejected.", "minLength": 1, "maxLength": 2000 } }, "required": ["reason"], "additionalProperties": false }, "GrantDecision": { "type": "object", "properties": { "side": { "type": "string", "description": "Side for which the caller has approval authority.", "enum": ["a", "b"] }, "decision": { "type": "string", "description": "Approve or reject the reviewed revision.", "enum": ["approve", "reject"] }, "reason": { "type": "string", "description": "Audited explanation.", "minLength": 1, "maxLength": 2000 } }, "required": ["side", "decision", "reason"], "additionalProperties": false }, "Resource": { "type": "object", "properties": { "resource_key": { "type": "string", "description": "Opaque qualified identity; never construct this value from a name.", "minLength": 1, "maxLength": 200 }, "product": { "type": "string", "description": "Source product.", "enum": ["infra", "guard", "custom"] }, "organization_id": { "type": "string", "description": "Source product organization.", "minLength": 1, "maxLength": 200 }, "installation_id": { "type": ["string", "null"], "description": "Source installation; null for custom records." }, "resource_type": { "type": "string", "description": "Native resource type, or service, deployment, or ticket for custom records.", "minLength": 1, "maxLength": 200 }, "resource_id": { "type": "string", "description": "Native ID or integration-scoped external ID.", "minLength": 1, "maxLength": 200 }, "source_revision": { "type": ["integer", "null"], "minimum": 1, "description": "Monotonic source revision; null when the source has no revision." }, "observed_at": { "type": "string", "description": "Time of the source observation.", "format": "date-time" }, "received_at": { "type": "string", "description": "Time Connector received the record.", "format": "date-time" }, "summary": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name.", "minLength": 1, "maxLength": 120 }, "state": { "type": "string", "description": "Source state; interpret using the source product." }, "url": { "type": "string", "description": "Permitted source detail URL.", "format": "uri" }, "labels": { "type": "object", "description": "Selected label keys and string values; at most 20 entries.", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 256 }, "default": {} }, "severity": { "type": "string", "description": "Security summary severity.", "enum": ["informational", "low", "medium", "high", "critical"] } }, "required": ["name"], "additionalProperties": false } }, "required": [ "resource_key", "product", "organization_id", "installation_id", "resource_type", "resource_id", "source_revision", "observed_at", "received_at", "summary" ], "additionalProperties": false }, "MappingCreate": { "type": "object", "properties": { "source_resource_key": { "type": "string", "description": "Qualified identity on one connection endpoint.", "minLength": 1, "maxLength": 200 }, "destination_resource_key": { "type": "string", "description": "Qualified identity on the other endpoint.", "minLength": 1, "maxLength": 200 }, "reason": { "type": "string", "description": "Why these records represent the same workload.", "minLength": 1, "maxLength": 2000 } }, "required": [ "source_resource_key", "destination_resource_key", "reason" ], "additionalProperties": false }, "Mapping": { "type": "object", "properties": { "id": { "type": "string", "description": "Mapping identity.", "minLength": 1, "maxLength": 200 }, "revision": { "type": "integer", "description": "Mapping revision.", "minimum": 1 }, "source_resource_key": { "type": "string", "description": "Confirmed source identity.", "minLength": 1, "maxLength": 200 }, "destination_resource_key": { "type": "string", "description": "Confirmed destination identity.", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "description": "Whether both referenced resources remain visible.", "enum": ["active", "stale"] }, "reason": { "type": "string", "description": "Audited association reason." } }, "required": [ "id", "revision", "source_resource_key", "destination_resource_key", "state", "reason" ], "additionalProperties": false }, "IntegrationCreate": { "type": "object", "properties": { "name": { "type": "string", "description": "Integration display name.", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "description": "Purpose of this integration.", "maxLength": 1000, "default": "" }, "homepage_url": { "type": "string", "description": "HTTPS location of the integration owner or application.", "format": "uri", "pattern": "^https://" }, "owner_team_id": { "type": "string", "description": "Responsible team in the owning Solarius organization.", "minLength": 1, "maxLength": 200 } }, "required": ["name", "homepage_url", "owner_team_id"], "additionalProperties": false }, "Integration": { "type": "object", "properties": { "id": { "type": "string", "description": "Registered integration identity.", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "description": "Display name.", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "description": "Purpose." }, "homepage_url": { "type": "string", "description": "Application HTTPS URL.", "format": "uri" }, "enabled": { "type": "boolean", "description": "Whether the integration can exchange records." }, "revision": { "type": "integer", "description": "Configuration revision.", "minimum": 1 }, "owner_team_id": { "type": "string", "description": "Responsible organization team.", "minLength": 1, "maxLength": 200 } }, "required": [ "id", "name", "description", "homepage_url", "enabled", "revision", "owner_team_id" ], "additionalProperties": false }, "IntegrationPatch": { "type": "object", "properties": { "name": { "type": "string", "description": "Replacement display name.", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "description": "Replacement purpose; empty clears the description.", "maxLength": 1000 }, "enabled": { "type": "boolean", "description": "true permits authorized exchange; false blocks subsequent exchange without deleting copies." } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "ExternalRecordWrite": { "type": "object", "properties": { "kind": { "type": "string", "description": "Immutable record category after creation.", "enum": ["service", "deployment", "ticket"] }, "name": { "type": "string", "description": "Name shown beside mapped native resources.", "minLength": 1, "maxLength": 120 }, "url": { "type": "string", "description": "HTTPS link to the source record; credentials and fragments are rejected.", "format": "uri", "pattern": "^https://" }, "state": { "type": "string", "description": "External lifecycle summary, not a Guard enforcement result.", "enum": ["unknown", "active", "resolved"] }, "labels": { "type": "object", "description": "Selected label keys and string values; at most 20 entries.", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 256 }, "default": {} } }, "required": ["kind", "name", "url", "state"], "additionalProperties": false }, "ExternalRecord": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Integration-scoped external identity.", "minLength": 1, "maxLength": 200 }, "integration_id": { "type": "string", "description": "Owning integration.", "minLength": 1, "maxLength": 200 }, "resource_key": { "type": "string", "description": "Connector identity used by resource mappings.", "minLength": 1, "maxLength": 200 }, "revision": { "type": "integer", "description": "Connector-assigned revision.", "minimum": 1 }, "record": { "$ref": "#/components/schemas/ExternalRecordWrite" }, "received_at": { "type": "string", "description": "Acceptance time.", "format": "date-time" } }, "required": [ "external_id", "integration_id", "resource_key", "revision", "record", "received_at" ], "additionalProperties": false }, "Event": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 1, "description": "Envelope format version." }, "event_id": { "type": "string", "description": "Stable event identity across attempts and replay.", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "description": "Event category.", "enum": [ "inventory.upserted", "inventory.removed", "security.summary.updated", "external.record.updated", "external.record.removed", "connection.state.changed", "mapping.changed", "operation.completed", "subscription.test" ] }, "organization_id": { "type": "string", "description": "Owning Solarius organization.", "minLength": 1, "maxLength": 200 }, "connection_id": { "type": "string", "description": "Approved connection.", "minLength": 1, "maxLength": 200 }, "grant_revision": { "type": "integer", "description": "Grant generation at event creation.", "minimum": 0 }, "occurred_at": { "type": "string", "description": "Time the source observation occurred.", "format": "date-time" }, "recorded_at": { "type": "string", "description": "Time the transport journal accepted the event.", "format": "date-time" }, "test": { "type": "boolean", "description": "true identifies a synthetic test; false identifies a source observation." }, "data": { "type": "object", "properties": { "resource_key": { "type": "string", "description": "Affected resource; omitted for connection or subscription events.", "minLength": 1, "maxLength": 200 }, "source_revision": { "type": "integer", "description": "Source revision when a resource has one.", "minimum": 1 }, "operation_id": { "type": "string", "description": "Product or Connector operation reference when present.", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "description": "Observed state or result when present." }, "severity": { "type": "string", "description": "Security summary severity when present.", "enum": ["informational", "low", "medium", "high", "critical"] } }, "required": [], "additionalProperties": false } }, "required": [ "schema_version", "event_id", "type", "organization_id", "connection_id", "grant_revision", "occurred_at", "recorded_at", "test", "data" ], "additionalProperties": false }, "SubscriptionCreate": { "type": "object", "properties": { "connection_id": { "type": "string", "description": "Connection whose approved events are delivered.", "minLength": 1, "maxLength": 200 }, "destination_url": { "type": "string", "description": "Public HTTPS receiver without credentials; private addresses and redirects are rejected.", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "description": "Explicit types; subscription.test is reserved for test requests.", "items": { "type": "string", "description": "Event category.", "enum": [ "inventory.upserted", "inventory.removed", "security.summary.updated", "external.record.updated", "external.record.removed", "connection.state.changed", "mapping.changed", "operation.completed" ] }, "minItems": 1, "uniqueItems": true }, "enabled": { "type": "boolean", "description": "Creation must use false; enabling requires a successful test.", "default": false, "const": false } }, "required": ["connection_id", "destination_url", "event_types"], "additionalProperties": false }, "SubscriptionPatch": { "type": "object", "properties": { "destination_url": { "type": "string", "description": "Replacement public HTTPS receiver; clears the successful test.", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "description": "Replacement selection; changing it clears the successful test.", "items": { "type": "string", "description": "Event category.", "enum": [ "inventory.upserted", "inventory.removed", "security.summary.updated", "external.record.updated", "external.record.removed", "connection.state.changed", "mapping.changed", "operation.completed" ] }, "minItems": 1, "uniqueItems": true }, "enabled": { "type": "boolean", "description": "true requires a successful test for the saved URL and filters; false stops subsequent deliveries." } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "description": "Subscription identity.", "minLength": 1, "maxLength": 200 }, "connection_id": { "type": "string", "description": "Bound connection.", "minLength": 1, "maxLength": 200 }, "destination_host": { "type": "string", "description": "Receiver host; full URL is not returned." }, "event_types": { "type": "array", "description": "Selected types.", "items": { "type": "string", "description": "Event category.", "enum": [ "inventory.upserted", "inventory.removed", "security.summary.updated", "external.record.updated", "external.record.removed", "connection.state.changed", "mapping.changed", "operation.completed" ] } }, "enabled": { "type": "boolean", "description": "Whether new deliveries are scheduled." }, "revision": { "type": "integer", "description": "Configuration revision.", "minimum": 1 }, "test_state": { "type": "string", "description": "Result for the saved configuration.", "enum": ["not_tested", "queued", "delivered", "failed"] } }, "required": [ "id", "connection_id", "destination_host", "event_types", "enabled", "revision", "test_state" ], "additionalProperties": false }, "SigningSecret": { "type": "object", "properties": { "id": { "type": "string", "description": "Secret version identity for Connector-Secret-Id.", "minLength": 1, "maxLength": 200 }, "secret": { "type": "string", "description": "Base64 encoding of 32 random bytes; present only in the first creation response and omitted on idempotent replay." }, "created_at": { "type": "string", "description": "Creation time.", "format": "date-time" } }, "required": ["id", "created_at"], "additionalProperties": false }, "SubscriptionCreated": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" }, "signing_secret": { "$ref": "#/components/schemas/SigningSecret" } }, "required": ["subscription", "signing_secret"], "additionalProperties": false }, "Delivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery identity.", "minLength": 1, "maxLength": 200 }, "event_id": { "type": "string", "description": "Stable source event identity.", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "description": "Receiver admission state.", "enum": ["queued", "retrying", "delivered", "failed", "suppressed"] }, "attempt_count": { "type": "integer", "description": "Attempts in this delivery window.", "minimum": 0, "maximum": 8 }, "last_status": { "type": ["integer", "null"], "minimum": 100, "maximum": 599, "description": "Last HTTP status; null for transport failures or no attempt." }, "retry_deadline": { "type": "string", "description": "End of the retry window, bounded by journal expiry.", "format": "date-time" } }, "required": [ "id", "event_id", "state", "attempt_count", "last_status", "retry_deadline" ], "additionalProperties": false }, "Operation": { "type": "object", "properties": { "id": { "type": "string", "description": "Connector operation identity.", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "description": "Execution result.", "enum": [ "queued", "running", "reconciling", "succeeded", "failed", "canceled" ] }, "cancelable": { "type": "boolean", "description": "Whether uncommitted work can be canceled." }, "revision": { "type": "integer", "description": "Operation revision for a cancellation precondition.", "minimum": 1 }, "result": { "type": "object", "properties": { "resource_id": { "type": "string", "description": "Result resource when available.", "minLength": 1, "maxLength": 200 }, "failed_resource_keys": { "type": "array", "description": "Resources whose exchange failed.", "items": { "type": "string", "description": "Resource key.", "minLength": 1, "maxLength": 200 } }, "source_operation_ids": { "type": "array", "description": "Native product references requiring independent inspection.", "items": { "type": "string", "description": "Source operation ID.", "minLength": 1, "maxLength": 200 } } }, "required": [], "additionalProperties": false }, "error": { "type": ["object", "null"], "description": "Null on success; failure code and recovery detail otherwise.", "properties": { "code": { "type": "string", "description": "Machine-readable reason." }, "message": { "type": "string", "description": "Recovery detail." } }, "required": ["code", "message"], "additionalProperties": false } }, "required": [ "id", "state", "cancelable", "revision", "result", "error" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable failure code." }, "message": { "type": "string", "description": "Condition and recovery detail." } }, "required": ["code", "message"], "additionalProperties": false }, "request_id": { "type": "string", "description": "Support correlation identity.", "minLength": 1, "maxLength": 200 } }, "required": ["error", "request_id"], "additionalProperties": false } }, "responses": { "401": { "description": "The key is missing, expired, revoked, or has the wrong API audience.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The principal lacks a required role, scope, binding, or product approval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource is missing or outside the caller permission boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The lifecycle, approval, dependency, or idempotency precondition conflicts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The requested cursor or retained journal event has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The supplied revision precondition does not match the current resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unknown fields, unsupported values, invalid types, or cross-field validation reject the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "A required revision precondition is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The configured request allowance is exhausted; respect Retry-After seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Whole seconds until retry.", "schema": { "type": "integer", "minimum": 1 } } } } } } }