{ "components": { "schemas": { "AccessResponse": { "properties": { "methods": { "items": { "$ref": "#/components/schemas/Method" }, "type": [ "array", "null" ] }, "rules": { "items": { "$ref": "#/components/schemas/RuleResponse" }, "type": [ "array", "null" ] } }, "type": "object" }, "AccessRule": { "description": "A single access-control rule applied to a connection. Today the only\nvariant is `Connection`, which targets a connection by its public\nconnection key. The serde tag `type` lets future variants\n(e.g. platform-wide rules) coexist without changing the wire shape.", "oneOf": [ { "description": "Restricts the key to a specific connection. The connection must\nalready exist within the same scope (org or project) as the key\nbeing configured; unresolved keys are rejected by the server.", "properties": { "actionIds": { "description": "Optional list of action IDs that further narrow the rule.\nWhen set, only these actions on the referenced connection\nare reachable; when omitted, all actions on the connection\nare permitted.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "connectionKey": { "description": "Public-facing key of the connection this rule targets,\nfor example `live::gmail::default`.", "type": "string" }, "methods": { "description": "HTTP methods allowed against this connection, overriding the\nrequest-level global list. Omitted inherits that list, or (in a\nconsent grant) permits every method \u2014 except that an\n`action_ids`-scoped rule never confers connection-record management,\nonly the listed actions.", "items": { "$ref": "#/components/schemas/Method" }, "type": [ "array", "null" ] }, "type": { "enum": [ "connection" ], "type": "string" } }, "required": [ "connectionKey", "type" ], "type": "object" } ] }, "ActivateEndpointParams": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/CreateRelayAction" }, "type": "array" }, "webhookSecret": { "type": [ "string", "null" ] } }, "required": [ "actions" ], "type": "object" }, "ActivateRequest": { "description": "The connector the activate leg stands up, named in the body beside the\n[`CeremonyQuery`] that names the ceremony.", "properties": { "connector": { "$ref": "#/components/schemas/ConnectionDefinitionId" } }, "required": [ "connector" ], "type": "object" }, "AgentPodView": { "properties": { "active": { "type": "boolean" }, "agentId": { "format": "uuid", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "podId": { "format": "uuid", "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "agentId", "podId", "createdAt", "updatedAt", "version", "tags", "active" ], "type": "object" }, "AiAgentChatTrigger": { "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "AiAgentCronRunStatusType": { "enum": [ "pending", "running", "completed", "failed" ], "type": "string" }, "AiAgentCronRunView": { "properties": { "agentId": { "format": "uuid", "type": "string" }, "completedAt": { "format": "date-time", "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "durationMs": { "format": "int32", "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "responsePreview": { "type": [ "string", "null" ] }, "scheduledAt": { "format": "date-time", "type": "string" }, "startedAt": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AiAgentCronRunStatusType" } }, "required": [ "id", "agentId", "scheduledAt", "status", "createdAt" ], "type": "object" }, "AiAgentCronSchedule": { "properties": { "deliverTo": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "enabled": { "type": "boolean" }, "expression": { "type": "string" }, "id": { "type": "string" }, "instructions": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "timezone": { "type": [ "string", "null" ] } }, "required": [ "id", "label", "enabled", "expression" ], "type": "object" }, "AiAgentModelType": { "enum": [ "haiku", "sonnet", "opus", "fable" ], "type": "string" }, "AiAgentSeatTrialOffer": { "description": "Where the caller stands with the free seat trial: `trialPeriodDays` when\none is on offer, `expiresAt` when one is running, neither once they have\ntransacted. An account with no billing record yet gets neither, which is\nan ordinary pre-onboarding state rather than an error.", "properties": { "expiresAt": { "description": "When a trial already running ends.", "format": "date-time", "type": [ "string", "null" ] }, "trialPeriodDays": { "description": "Free days a checkout would attach, when the caller is still eligible.", "format": "int32", "minimum": 0, "type": [ "integer", "null" ] } }, "type": "object" }, "AiAgentStatusType": { "enum": [ "active", "paused", "disabled" ], "type": "string" }, "AiAgentTriggers": { "properties": { "chat": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiAgentChatTrigger" } ] }, "cronSchedules": { "items": { "$ref": "#/components/schemas/AiAgentCronSchedule" }, "type": "array" }, "webhookSubscriptions": { "items": { "$ref": "#/components/schemas/AiAgentWebhookSubscription" }, "type": "array" } }, "type": "object" }, "AiAgentView": { "properties": { "active": { "type": "boolean" }, "channels": {}, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "guardrails": {}, "id": { "format": "uuid", "type": "string" }, "memory": {}, "model": { "$ref": "#/components/schemas/AiAgentModelType" }, "modelId": { "type": [ "string", "null" ] }, "modelProvider": { "$ref": "#/components/schemas/AiModelProviderType" }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "runnerStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PodStatusType", "description": "The state of this agent's runner, when it has one.\n\nThe agent's own lifecycle and its pod's are separate, and this field is\nwhat lets a caller see the second without conflating it into the first.\nAn agent that has never been run has no pod and reports `None`; one\nwhose pod was stopped - by the owner, or by a lapsed seat culling it -\nreports [`PodStatusType::Terminated`], which is what a console renders\nas paused.\n\nPopulated only by the read paths that opt in through\n[`ViewWithCtxExt::into_view_with_ctx`], so the write paths pay nothing\nfor it.\nAbsent from the wire rather than null when there is no runner, so a\nresponse for an agent that has never run is byte-identical to before." } ] }, "runnerStopReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PodStopReasonType", "description": "What stopped the runner, when it is stopped.\n\n`runnerStatus` alone cannot say: a pause the owner performed and a stop\nbilling performed both read `terminated`, which is the whole reason this\nexists. Absent while the runner is live, and on pods stopped before it\nwas recorded.\n\n**A cause, not a prediction.** It records the stop that happened and\nnothing re-derives it afterwards, so entitlement can move underneath it\nin both directions: an owner-paused agent stays `user_requested` when\nits seat later lapses, because the cull only counts what is running,\nyet `ensure` counts every undeleted agent and will refuse it; and a\nculled agent stays `seat_lapsed` after a replacement seat is bought,\nuntil a resume clears it. Use it to explain what happened - and ask\n`ensure` whether the agent can start, rather than guessing from\nthis." } ] }, "runtime": { "$ref": "#/components/schemas/AiRuntimeType" }, "status": { "$ref": "#/components/schemas/AiAgentStatusType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "tools": {}, "trialSeat": { "description": "Whether this agent occupies the owner's free-trial seat.\n\nWorth surfacing because it decides what happens when the trial ends:\nthis is the agent stopped first, ahead of the least recently used. It\nis also the only way a caller learns whether a `useTrial` create took\neffect, since that flag is ignored rather than rejected when there is\nno live trial or another agent already holds the seat.\n\nAbsent from the wire rather than `false` on the paths that do not\nresolve it, so \"not on the trial seat\" is never confused with \"not\nasked\".", "type": [ "boolean", "null" ] }, "triggers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiAgentTriggers" } ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" }, "volumeId": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "id", "userId", "name", "model", "status", "tools", "environment", "runtime", "modelProvider", "createdAt", "updatedAt", "version", "tags", "active" ], "type": "object" }, "AiAgentWebhookSubscription": { "properties": { "actionId": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "enabled": { "type": [ "boolean", "null" ] }, "id": { "type": [ "string", "null" ] }, "instructions": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "relayId": { "type": [ "string", "null" ] }, "relayUrl": { "type": [ "string", "null" ] }, "thirdPartyWebhookId": { "type": [ "string", "null" ] } }, "type": "object" }, "AiModelProviderType": { "description": "The model provider powering a framework agent's brain. Values mirror the\nwire ids the console has always written into `memory.modelProvider`\n(`openai-api`, not `openai`) so the typed column and the historical\nmarker can never disagree. Stored as text (the `Role` pattern) \u2014 the\nclosed set lives here in Rust, so admitting a provider is a code change,\nnever a Postgres enum migration.", "enum": [ "anthropic", "openai-api", "gemini" ], "type": "string" }, "AiRunnerView": { "properties": { "agentId": { "format": "uuid", "type": "string" }, "dashboardPassword": { "description": "Always `None` on this status/lifecycle view. The dashboard password is\nnever returned alongside pod status \u2014 surfacing it here would ride every\npoll. It is returned only by the dedicated reveal / regenerate routes,\nwhich respond with a [`DashboardPasswordView`].", "type": [ "string", "null" ] }, "dashboardUsername": { "description": "Framework (Hermes) dashboard basic-auth username \u2014 the fixed `one`\naccount. Populated (decrypted) only on the owner-authed status route\nfor framework pods; `None` for Claude and on the ensure/resume\nconstruction sites. `skip_serializing_if` keeps the Claude status\nresponse byte-identical (the key is absent, not `null`).", "type": [ "string", "null" ] }, "link": { "$ref": "#/components/schemas/AgentPodView" }, "pod": { "$ref": "#/components/schemas/PodView" } }, "required": [ "agentId", "pod", "link" ], "type": "object" }, "AiRuntimeType": { "enum": [ "claude", "hermes", "openclaw", "clockwork" ], "type": "string" }, "AiSkillId": { "description": "Prefixed ID with 'ai_skill' prefix (e.g., 'ai_skill_1C'), also accepts raw integer", "type": "string" }, "AiSkillVersionId": { "description": "Prefixed ID with 'ai_skill_ver' prefix (e.g., 'ai_skill_ver_1C'), also accepts raw integer", "type": "string" }, "AiSkillVersionView": { "properties": { "agent": { "type": [ "string", "null" ] }, "aiSkillId": { "$ref": "#/components/schemas/AiSkillId" }, "allowedTools": {}, "argumentHint": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "disableModelInvocation": { "type": "boolean" }, "hooks": {}, "id": { "$ref": "#/components/schemas/AiSkillVersionId" }, "model": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "publishedAt": { "format": "date-time", "type": "string" }, "publishedBy": { "format": "uuid", "type": "string" }, "rejectReason": { "type": [ "string", "null" ] }, "rejectedAt": { "format": "date-time", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "userInvocable": { "type": "boolean" }, "verifiedAt": { "format": "date-time", "type": [ "string", "null" ] }, "versionNumber": { "format": "int32", "type": "integer" }, "yankedAt": { "format": "date-time", "type": [ "string", "null" ] }, "yankedBy": { "format": "uuid", "type": [ "string", "null" ] }, "yankedReason": { "type": [ "string", "null" ] } }, "required": [ "id", "aiSkillId", "versionNumber", "name", "description", "content", "disableModelInvocation", "userInvocable", "tags", "publishedAt", "publishedBy" ], "type": "object" }, "AiSkillView": { "properties": { "active": { "type": "boolean" }, "agent": { "type": [ "string", "null" ] }, "allowedTools": {}, "argumentHint": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "disableModelInvocation": { "type": "boolean" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "hooks": {}, "id": { "$ref": "#/components/schemas/AiSkillId" }, "lastUsedAt": { "format": "date-time", "type": [ "string", "null" ] }, "latestPublishedVersionId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiSkillVersionId" } ] }, "model": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "public": { "type": "boolean" }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "usageCount": { "format": "int32", "type": "integer" }, "userId": { "format": "uuid", "type": "string" }, "userInvocable": { "type": "boolean" }, "version": { "type": "string" } }, "required": [ "id", "userId", "name", "description", "content", "disableModelInvocation", "userInvocable", "environment", "usageCount", "createdAt", "updatedAt", "version", "tags", "active", "public" ], "type": "object" }, "AllowedActionView": { "properties": { "id": { "description": "The action's **`system_id`**, not its row id.\n\nThis is the identifier a rule's `actionIds` carries and the one both\nthe permission-set editor and the consent submission are validated\nagainst, so it is the only id a client can send back. Publishing the\nrow id instead round-trips into an action that resolves to a different\nconnector, which consent now refuses as foreign.", "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "ApiKeyCreatedPayload": { "description": "Identifies the key without ever carrying its material - the secret exists\nonly in the create response, never in a delivery.", "properties": { "connection_type": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "environment": { "type": "string" }, "event_access_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "format": "uuid", "type": [ "string", "null" ] }, "project_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "event_access_id", "connection_type", "environment", "created_at" ], "type": "object" }, "ApiKeyRevokedPayload": { "properties": { "connection_type": { "type": "string" }, "environment": { "type": "string" }, "event_access_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "format": "uuid", "type": [ "string", "null" ] }, "project_id": { "format": "uuid", "type": [ "string", "null" ] }, "revoked_at": { "format": "date-time", "type": "string" } }, "required": [ "event_access_id", "connection_type", "environment", "revoked_at" ], "type": "object" }, "AuthMethod": { "enum": [ "BearerToken", "ApiKey", "BasicAuth", "OAuthLegacy", "QueryParam", "OAuth", "None" ], "type": "string" }, "AuthMethodView": { "properties": { "authMethodType": { "$ref": "#/components/schemas/AuthMethod" }, "hashAlgorithm": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HashAlgorithm", "description": "Ensured to have a value when auth method types are:\n- `OAuthLegacy`" } ] }, "key": { "description": "Ensured to have a value when auth method types are:\n- `ApiKey`\n- `QueryParam`", "type": [ "string", "null" ] }, "password": { "description": "Ensured to have a value when auth method types are:\n- `BasicAuth`", "type": [ "string", "null" ] }, "realm": { "description": "Ensured to have a value when auth method types are:\n- `OAuthLegacy`", "type": [ "string", "null" ] }, "username": { "description": "Ensured to have a value when auth method types are:\n- `BasicAuth`", "type": [ "string", "null" ] }, "value": { "description": "Ensured to have a value when auth method types are:\n- `ApiKey`\n- `QueryParam`\n- `BearerToken`", "type": [ "string", "null" ] } }, "required": [ "authMethodType" ], "type": "object" }, "AuthorizationReachView": { "description": "What one app reaches in one environment, as the manage page reads it.\n\n**Deliberately not folded into a single view.** A grant is per environment,\nand `Full` in one says nothing about the other: merging them would report a\nnarrowed live grant as unrestricted the moment a sandbox grant sat beside\nit, and drop every account the user came to edit. Keeping them apart is also\nwhat lets the page say which environment a level belongs to, which is the\nquestion a single merged answer cannot even express.", "properties": { "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "reach": { "description": "What a grant reaches, generic over how each entry is rendered - the one\ntrichotomy two surfaces share: a dashboard reads it as counts\n([`GrantedReachView`]), a reconnect card as pre-selectable rules\n([`PriorGrantView`]). `KnowledgeOnly`/`Full` are identical on the wire for\nboth; only the `Connectors` element type differs.\n\nA bare generic derives a single schema named `ReachView`, so both\ninstantiations would collide on that one OpenAPI component and one endpoint\nwould advertise the other's connector shape. Every schema site that carries\none of these therefore inlines it (`#[schema(inline)]` / `inline(...)`), so\nno shared `ReachView` component exists to collide.", "oneOf": [ { "description": "Docs and search only: no connection access of any kind.", "properties": { "type": { "enum": [ "knowledgeOnly" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Every connection in the consented scope. No connector list because the\ngrant names none - it follows the account.", "properties": { "type": { "enum": [ "full" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Only what the grant names, each entry rendered as `C`. **The granularity\nis the instantiation's**: a reach report carries one entry per\nconnector, a prior grant one per granted *connection*, so two entries\nthere can share a connector.", "properties": { "connectors": { "items": { "$ref": "#/components/schemas/PriorGrantConnectorView" }, "type": "array" }, "type": { "enum": [ "connectors" ], "type": "string" } }, "required": [ "connectors", "type" ], "type": "object" } ] } }, "required": [ "environment", "reach" ], "type": "object" }, "AvailableActionsView": { "properties": { "key": { "type": "string" }, "method": { "$ref": "#/components/schemas/Method" }, "modelName": { "type": "string" }, "path": { "type": "string" }, "systemId": { "description": "Stable id for this action. Use as `actionId` for passthrough /\nexecute calls; survives renames of `key` or `title`.", "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "systemId", "title", "key", "modelName", "method", "path", "tags" ], "type": "object" }, "AvailableActionsWithKnowledgeView": { "properties": { "key": { "type": "string" }, "knowledge": { "type": [ "string", "null" ] }, "method": { "$ref": "#/components/schemas/Method" }, "path": { "type": "string" }, "systemId": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "systemId", "title", "key", "method", "path", "tags" ], "type": "object" }, "AvailableConnectorView": { "properties": { "active": { "type": "boolean" }, "category": { "type": "string" }, "description": { "type": "string" }, "id": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "image": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "oauth": { "type": "boolean" }, "oauthScopes": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthScopesView" } ] }, "platform": { "type": "string" }, "platformVersion": { "type": "string" }, "status": { "$ref": "#/components/schemas/ConnectionStatusType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": [ "string", "null" ] }, "tools": { "format": "int32", "type": "integer" }, "version": { "type": "string" } }, "required": [ "id", "name", "platformVersion", "status", "key", "platform", "description", "category", "image", "tags", "tools", "oauth", "version", "active" ], "type": "object" }, "BrandingSnapshot": { "properties": { "customerFacingName": { "type": "string" }, "darkLogoUrl": { "type": [ "string", "null" ] }, "lightLogoUrl": { "type": [ "string", "null" ] }, "successMessage": { "type": "string" }, "welcomeMessage": { "type": "string" } }, "required": [ "customerFacingName", "welcomeMessage", "successMessage" ], "type": "object" }, "CeremonyConnectResponse": { "allOf": [ { "$ref": "#/components/schemas/Paginated_ConnectedPlatformView" }, { "properties": { "requestId": { "$ref": "#/components/schemas/OAuthRequestId" } }, "required": [ "requestId" ], "type": "object" } ], "description": "What the card renders its platform tiles from.\n\nShaped like `InitResponse`, which the dashboard's AuthKit legs return, and\nover the same [`ConnectedPlatformView`]: the card's embedded auth widget\nroutes a tile into its OAuth flow only when the row carries the OAuth\nfields, so the ceremony hands back the one full shape the widget already\nconsumes on the dashboard rather than a trimmed variant it dead-ends on. No\ncredential rides along - the masked secret display is truncated at write and\nthe real secret stays behind `secret_id`." }, "CeremonyConnectionView": { "description": "One connection the card may be told about: enough to mark a connector as\nalready connected, and nothing more.\n\n**Not `ConnectionView`.** That carries `secret_id`, `webhook_secret_id`,\n`identity`, the owning `user_id` and the whole `change_log` - none of which\na consent screen needs, and all of which would be handed to a surface whose\nentire job is to be embedded in somebody else's page. What stays is what the\ncard acts on: which connector, which connection, and whether it is healthy.", "properties": { "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId", "description": "Which connector, so the card can match it against the ceremony's offer." }, "key": { "description": "The connection's public key, and the reason this view is not narrower\nstill: a restricted consent names a connection through\n`AccessRule::Connection`, which is keyed on exactly this. Without it a\ncard that wants to include a connection the user already has cannot\nname it, and has to fall back to a connector-wide grant - so omitting\nit made the resulting grant *wider*, not tighter.", "type": "string" }, "name": { "description": "The user's own label for it, when they gave one.", "type": [ "string", "null" ] }, "platform": { "type": "string" }, "state": { "$ref": "#/components/schemas/ConnectionStateType" }, "tags": { "description": "The user's own tags, so the card can tell two accounts on one connector\napart at a glance. Empty when they tagged it with none.", "items": { "type": "string" }, "type": "array" } }, "required": [ "connectionDefinitionId", "key", "platform", "state", "tags" ], "type": "object" }, "ChangeLog": { "type": "object" }, "CheckoutSessionResponse": { "properties": { "checkoutUrl": { "type": "string" } }, "required": [ "checkoutUrl" ], "type": "object" }, "ClientUserView": { "description": "One user's standing with an OAuth client, as its developer sees them.\n\nCarries `reach` in the same consent vocabulary as\n[`crate::domain::oauth_authorization::OAuthAuthorizationView`], so the two\nsides of the ledger report a grant identically.", "properties": { "createdAt": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "expiresAt": { "description": "When the user's current access token for this client expires. `None`\nwhile they hold a live grant but no live token - the window between\nre-consent and the client redeeming the new code.", "format": "date-time", "type": [ "string", "null" ] }, "lastUsedAt": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "reach": { "description": "What a grant reaches, generic over how each entry is rendered - the one\ntrichotomy two surfaces share: a dashboard reads it as counts\n([`GrantedReachView`]), a reconnect card as pre-selectable rules\n([`PriorGrantView`]). `KnowledgeOnly`/`Full` are identical on the wire for\nboth; only the `Connectors` element type differs.\n\nA bare generic derives a single schema named `ReachView`, so both\ninstantiations would collide on that one OpenAPI component and one endpoint\nwould advertise the other's connector shape. Every schema site that carries\none of these therefore inlines it (`#[schema(inline)]` / `inline(...)`), so\nno shared `ReachView` component exists to collide.", "oneOf": [ { "description": "Docs and search only: no connection access of any kind.", "properties": { "type": { "enum": [ "knowledgeOnly" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Every connection in the consented scope. No connector list because the\ngrant names none - it follows the account.", "properties": { "type": { "enum": [ "full" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Only what the grant names, each entry rendered as `C`. **The granularity\nis the instantiation's**: a reach report carries one entry per\nconnector, a prior grant one per granted *connection*, so two entries\nthere can share a connector.", "properties": { "connectors": { "items": { "$ref": "#/components/schemas/GrantedConnectorView" }, "type": "array" }, "type": { "enum": [ "connectors" ], "type": "string" } }, "required": [ "connectors", "type" ], "type": "object" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "tokenCount": { "minimum": 0, "type": "integer" }, "userId": { "format": "uuid", "type": "string" }, "username": { "type": "string" } }, "required": [ "userId", "email", "username", "scopes", "reach", "createdAt", "tokenCount" ], "type": "object" }, "ConfigureAccessParams": { "additionalProperties": false, "description": "Body for the configure-key endpoints. Replaces (not merges) the access\nrules on an API key; at least one of `methods` or `rules` must be present.\n\n**Scope: passthrough only.** `methods` and `rules` are evaluated only when\nthe key calls the passthrough API (the proxy to the external platform).\nThey do NOT gate first-party endpoints (`/v1/connections/*` CRUD, webhooks,\nvault, \u2026), which stay authorized by the key's role and tenancy.", "properties": { "methods": { "description": "Global allow-list for passthrough calls only. Matched against the\n**semantic CRUD method** (`Get`/`Post`/\u2026) on the targeted action\ndefinition, NOT the incoming request's HTTP method. Per-connection\n`rules` can override it. `null`/omitted leaves it unset (every semantic\nmethod allowed globally).", "items": { "$ref": "#/components/schemas/Method" }, "type": [ "array", "null" ] }, "rules": { "description": "Per-connection rules for passthrough calls only. When present, the\npassthrough API can only reach the connections these rules reference.\nEach rule targets a connection by `connectionKey` and may override the\nglobal `methods` or narrow via `actionIds`. See the `AccessRule` schema.", "items": { "$ref": "#/components/schemas/AccessRule" }, "type": [ "array", "null" ] } }, "type": "object" }, "ConnectedPlatformId": { "description": "Prefixed ID with 'conn_plf' prefix (e.g., 'conn_plf_1C'), also accepts raw integer", "type": "string" }, "ConnectedPlatformView": { "properties": { "activatedAt": { "format": "date-time", "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "clientIdDisplay": { "type": [ "string", "null" ] }, "clientSecretDisplay": { "type": [ "string", "null" ] }, "connectionDefId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "createdAt": { "format": "date-time", "type": "string" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "guide": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/ConnectedPlatformId" }, "image": { "type": "string" }, "scopes": { "type": [ "string", "null" ] }, "secretId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "type": { "type": "string" }, "useDefaultOauthCreds": { "type": "boolean" } }, "required": [ "id", "connectionDefId", "type", "title", "image", "environment", "createdAt", "tags", "active", "useDefaultOauthCreds" ], "type": "object" }, "ConnectionAccess": { "description": "The access a grant confers on one connection, surfaced to the MCP client so\nthe agent knows what it can run without probing. Derived from the grant's\n[`AccessRules`]: no rule (or an unrestricted one) is [`ConnectionAccess::Full`],\na method-scoped rule is [`ConnectionAccess::Methods`], and an action-scoped\nrule is [`ConnectionAccess::Actions`] with each id resolved to its title and\nmethod.", "oneOf": [ { "description": "Every action on the connection.", "properties": { "policy": { "enum": [ "full" ], "type": "string" } }, "required": [ "policy" ], "type": "object" }, { "description": "Only actions whose semantic HTTP method is in this set.", "properties": { "methods": { "items": { "$ref": "#/components/schemas/Method" }, "type": "array" }, "policy": { "enum": [ "methods" ], "type": "string" } }, "required": [ "methods", "policy" ], "type": "object" }, { "description": "Only these specific actions.", "properties": { "actions": { "items": { "$ref": "#/components/schemas/GrantedAction" }, "type": "array" }, "policy": { "enum": [ "actions" ], "type": "string" } }, "required": [ "actions", "policy" ], "type": "object" } ] }, "ConnectionCreatedPayload": { "properties": { "connection_id": { "format": "uuid", "type": "string" }, "connection_type": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "environment": { "type": "string" }, "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "format": "uuid", "type": [ "string", "null" ] }, "platform": { "type": "string" }, "project_id": { "format": "uuid", "type": [ "string", "null" ] }, "state": { "type": "string" } }, "required": [ "connection_id", "key", "platform", "environment", "connection_type", "state", "created_at" ], "type": "object", "x-one-connection-scoped": true }, "ConnectionDefinitionFrontend": { "properties": { "connectionForm": { "$ref": "#/components/schemas/ConnectionForm" }, "spec": { "$ref": "#/components/schemas/Spec" } }, "required": [ "spec", "connectionForm" ], "type": "object" }, "ConnectionDefinitionId": { "description": "Prefixed ID with 'conn_def' prefix (e.g., 'conn_def_1C'), also accepts raw integer", "type": "string" }, "ConnectionDefinitionView": { "properties": { "_id": { "format": "int32", "type": "integer" }, "active": { "type": "boolean" }, "authMethod": { "$ref": "#/components/schemas/AuthMethodView" }, "authSecrets": { "items": { "type": "string" }, "type": "array" }, "authentication": { "type": [ "string", "null" ] }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "frontend": { "$ref": "#/components/schemas/ConnectionDefinitionFrontend" }, "id": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "key": { "type": "string" }, "name": { "type": "string" }, "oauth": { "type": "boolean" }, "platform": { "type": "string" }, "platformVersion": { "type": "string" }, "status": { "$ref": "#/components/schemas/ConnectionStatusType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "type": { "$ref": "#/components/schemas/ConnectionType" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "_id", "platformVersion", "platform", "status", "key", "type", "authMethod", "name", "authSecrets", "frontend", "oauth", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "ConnectionDeletedPayload": { "properties": { "connection_id": { "format": "uuid", "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "key": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "organization_id": { "format": "uuid", "type": [ "string", "null" ] }, "platform": { "type": "string" }, "project_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "connection_id", "platform", "deleted_at" ], "type": "object", "x-one-connection-scoped": true }, "ConnectionForm": { "properties": { "description": { "type": "string" }, "formData": { "items": { "$ref": "#/components/schemas/FormDataItem" }, "type": "array" }, "name": { "type": "string" } }, "required": [ "name", "description", "formData" ], "type": "object" }, "ConnectionIdentityType": { "enum": [ "organization", "user", "team", "project" ], "type": "string" }, "ConnectionMetricItem": { "properties": { "createdAt": { "type": "string" }, "environment": { "type": "string" }, "platform": { "type": "string" } }, "required": [ "platform", "environment", "createdAt" ], "type": "object" }, "ConnectionMetrics": { "properties": { "byEnvironment": { "items": { "$ref": "#/components/schemas/MetricBreakdown" }, "type": "array" }, "byPlatform": { "items": { "$ref": "#/components/schemas/MetricBreakdown" }, "type": "array" }, "connections": { "items": { "$ref": "#/components/schemas/ConnectionMetricItem" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "total", "connections", "byEnvironment", "byPlatform" ], "type": "object" }, "ConnectionModelDefinitionId": { "description": "Prefixed ID with 'conn_mod_def' prefix (e.g., 'conn_mod_def_1C'), also accepts raw integer", "type": "string" }, "ConnectionOAuthCreatedPayload": { "properties": { "authorized_at": { "format": "date-time", "type": "string" }, "connection_id": { "format": "uuid", "type": "string" }, "key": { "type": "string" }, "platform": { "type": "string" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "connection_id", "platform", "key", "user_id", "authorized_at" ], "type": "object", "x-one-connection-scoped": true }, "ConnectionOAuthDefinitionFrontend": { "description": "Frontend configuration for OAuth flows\n\nThis is flow-specific configuration stored in the database.\nFor backward compatibility, deserializes old structs as AuthorizationCode\nvariant.", "oneOf": [ { "description": "Authorization Code flow configuration (includes redirect URIs)", "properties": { "AuthorizationCode": { "description": "Authorization Code flow configuration (includes redirect URIs)", "properties": { "ios_redirect_uri": { "type": "string" }, "platform_redirect_uri": { "type": "string" }, "sandbox_platform_redirect_uri": { "type": [ "string", "null" ] }, "scopes": { "type": "string" }, "separator": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] } }, "required": [ "platform_redirect_uri", "scopes", "ios_redirect_uri" ], "type": "object" } }, "required": [ "AuthorizationCode" ], "type": "object" }, { "description": "Client Credentials flow configuration (no redirect URIs needed)", "properties": { "ClientCredentials": { "description": "Client Credentials flow configuration (no redirect URIs needed)", "properties": { "scopes": { "type": "string" }, "separator": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "scopes" ], "type": "object" } }, "required": [ "ClientCredentials" ], "type": "object" } ] }, "ConnectionOAuthDefinitionId": { "description": "Prefixed ID with 'conn_oauth_def' prefix (e.g., 'conn_oauth_def_1C'), also accepts raw integer", "type": "string" }, "ConnectionOAuthDefinitionView": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "configuration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthOverrides" } ] }, "connectionDefId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "connectionPlatform": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "flowType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthFlowType" } ] }, "frontend": { "$ref": "#/components/schemas/ConnectionOAuthDefinitionFrontend" }, "id": { "$ref": "#/components/schemas/ConnectionOAuthDefinitionId" }, "renderWithSecret": { "type": "boolean" }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "connectionDefId", "connectionPlatform", "frontend", "renderWithSecret", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "ConnectionStateType": { "enum": [ "operational", "degraded", "failed", "unknown" ], "type": "string" }, "ConnectionStatusType": { "enum": [ "not_available", "beta", "alpha", "generally_available" ], "type": "string" }, "ConnectionType": { "enum": [ "api", "databasesql", "databasenosql", "filesystem", "stream", "custom" ], "type": "string" }, "ConnectionUpdatedPayload": { "description": "Carries the connection's state after the change, so a subscriber can apply\nit without refetching.", "properties": { "connection_id": { "format": "uuid", "type": "string" }, "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "format": "uuid", "type": [ "string", "null" ] }, "platform": { "type": "string" }, "project_id": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "connection_id", "key", "platform", "tags", "updated_at" ], "type": "object", "x-one-connection-scoped": true }, "ConnectionView": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "connectionOauthDefId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionOAuthDefinitionId" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "expiresAt": { "format": "date-time", "type": [ "string", "null" ] }, "expiresIn": { "format": "int64", "type": [ "integer", "null" ] }, "group": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "identity": { "type": [ "string", "null" ] }, "identityType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionIdentityType" } ] }, "image": { "type": [ "string", "null" ] }, "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "platformVersion": { "type": "string" }, "secretId": { "format": "uuid", "type": "string" }, "state": { "$ref": "#/components/schemas/ConnectionStateType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/ConnectionType" }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" }, "webhookSecretId": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "id", "platformVersion", "connectionDefinitionId", "type", "group", "key", "environment", "platform", "secretId", "state", "userId", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "ConnectorRule": { "oneOf": [ { "properties": { "actionIds": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "methods": { "items": { "$ref": "#/components/schemas/Method" }, "type": [ "array", "null" ] }, "type": { "enum": [ "connectionDefinition" ], "type": "string" } }, "required": [ "connectionDefinitionId", "type" ], "type": "object" } ] }, "ConsentContext": { "description": "Everything the connect card needs to render one consent ceremony.", "properties": { "allowAll": { "description": "True when the ceremony named no permission set (or the allow-all set),\nso the app offers the whole catalog. The card renders the offerable\ncatalog as prospective in that case; without this it could not tell\n\"everything\" from an enumerated set that resolved to zero\nconnectors, which activate would then refuse.", "type": "boolean" }, "clientName": { "description": "Display name of the app asking for access.", "type": "string" }, "connectors": { "description": "The connectors the ceremony offers, resolved from the permission-set\nsnapshot frozen onto the placeholder at authorize time. Empty for an\nallow-all ceremony and for an enumerated set whose connectors are all\ndelisted; `allow_all` is what tells the two apart.", "items": { "$ref": "#/components/schemas/ResolvedConnectorView" }, "type": "array" }, "frameAncestors": { "description": "The origins allowed to frame this card, as a `frame-ancestors` source\nlist: the client's registered redirect-URI origins, or `'none'` when it\nhas none that parse.\n\n**Core cannot enforce this, and that is why it is here.** A\n`frame-ancestors` policy governs the response it rides on, and the card\ndocument is served by the frontend, not by this server - a policy on the\nredirect that sends a browser there protects nothing. Whoever serves the\ncard has to emit it, and this is where they get the answer: the ceremony\nnames the client, the client's redirect origins are already its proven\nproperty, and both are known here.", "type": "string" }, "loginHint": { "description": "Email the authorize URL suggested, for the card to pre-fill its sign-in\nfield. Never a restriction: a user who types a different address signs\nin as that one.", "type": [ "string", "null" ] }, "logoUrl": { "description": "The app's logo, as its owner registered it. `None` when they registered\nnone, which is the card's cue to fall back to whatever placeholder it\ndraws.", "type": [ "string", "null" ] }, "viewer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConsentViewer", "description": "`None` until somebody signs in, which serializes as JSON `null` and is\nwhat tells the card to render sign-in.\n\nDeliberately **not** `skip_serializing_if`: the absence of a viewer is\nthe answer this endpoint exists to give, so the key has to be present\nand null rather than missing. A card written against the documented\ncontract - or a generated client typing this as `Viewer | null` - would\nnever see the field at all if it were skipped, and so would never\nrender sign-in." } ] } }, "required": [ "clientName", "connectors", "allowAll", "frameAncestors" ], "type": "object" }, "ConsentOrganization": { "description": "One organization a consent ceremony can be scoped to.", "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "ConsentProject": { "description": "One project a consent ceremony can be scoped to, and the organization it\nbelongs to.", "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": "string" } }, "required": [ "id", "name", "organizationId" ], "type": "object" }, "ConsentSurface": { "description": "Where an OAuth client's users are sent to grant consent.\n\nThe surface used to be read off the client id, so a client could only get a\ndifferent one by being renamed, and every existing client would have moved\nthe moment the rule changed. Naming it on the row makes it a property of the\nclient that its owner can see and set, and leaves the ones already running\nexactly where they are.", "enum": [ "hosted", "connect" ], "type": "string" }, "ConsentTenancy": { "description": "The tenants a user may grant a consent ceremony against.", "properties": { "organizations": { "items": { "$ref": "#/components/schemas/ConsentOrganization" }, "type": "array" }, "projects": { "items": { "$ref": "#/components/schemas/ConsentProject" }, "type": "array" } }, "required": [ "organizations", "projects" ], "type": "object" }, "ConsentViewer": { "description": "Who the ceremony is being shown to. Absent - JSON `null` - is what tells\nthe card to render sign-in.", "properties": { "email": { "description": "The address the card labels the session with - \"signed in as \u2026\".\n\nTheir own, and only ever their own: this is populated from the row the\nsession's user id names, after the ceremony has been proved claimable by\nthat same user, so a state-key holder cannot read it for anybody else.", "type": "string" }, "tenancy": { "$ref": "#/components/schemas/ConsentTenancy", "description": "The tenants this user may scope the grant to. Only ever populated for a\nsigned-in viewer, because it is their own tenancy." }, "userId": { "format": "uuid", "type": "string" } }, "required": [ "userId", "email", "tenancy" ], "type": "object" }, "CreateAiAgentParams": { "properties": { "channels": {}, "description": { "type": [ "string", "null" ] }, "guardrails": {}, "memory": {}, "model": { "$ref": "#/components/schemas/AiAgentModelType" }, "modelId": { "type": [ "string", "null" ] }, "modelProvider": { "$ref": "#/components/schemas/AiModelProviderType" }, "name": { "type": "string" }, "runtime": { "$ref": "#/components/schemas/AiRuntimeType" }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "tools": {}, "triggers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiAgentTriggers" } ] }, "useTrial": { "description": "Put this agent on the caller's free-trial seat. Ignored when they have\nno live trial, or when its seat is already taken by another agent.", "type": "boolean" }, "volumeId": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "name", "model", "tools" ], "type": "object" }, "CreateAiSkillParams": { "additionalProperties": false, "properties": { "agent": { "type": [ "string", "null" ] }, "allowedTools": {}, "argumentHint": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "disableModelInvocation": { "type": [ "boolean", "null" ] }, "hooks": {}, "model": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "skipValidation": { "type": [ "boolean", "null" ] }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "userInvocable": { "type": [ "boolean", "null" ] } }, "required": [ "name", "description", "content" ], "type": "object" }, "CreateEndpointParams": { "properties": { "connectionKey": { "type": "string" }, "createWebhook": { "type": [ "boolean", "null" ] }, "description": { "type": [ "string", "null" ] }, "eventFilters": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "connectionKey" ], "type": "object" }, "CreateInvitationParams": { "additionalProperties": false, "description": "Body for invitation-create endpoints (org and project).", "properties": { "email": { "type": "string" }, "expiresAt": { "description": "Optional expiration in ISO 8601 / RFC 3339 format.", "format": "date-time", "type": [ "string", "null" ] }, "roleKey": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RoleHierarchy", "description": "Optional role for the invitee. Wire format matches the enum\nvariant exactly (`Member`, `Manager`, `Admin`). Defaults to\n`Member` when omitted." } ] } }, "required": [ "email" ], "type": "object" }, "CreateOrganizationKeyParams": { "additionalProperties": false, "description": "Body for `POST /v1/management/organizations/{org_id}/keys`.\n\nMints an additional regular organization-scoped API key. Same\nreasoning as [`CreateProjectKeyParams`]: `connectionType` is fixed\nto `api` internally, and the environment is inherited from the\ncalling credential.", "properties": { "name": { "description": "Optional label for the new key (shown in the dashboard's API\nkeys list). When omitted, the key is unnamed.", "type": [ "string", "null" ] } }, "type": "object" }, "CreateParams": { "properties": { "accessTokenTtl": { "description": "Access-token lifetime in seconds. One of the offered choices, or null for the platform default; any other value is refused.", "enum": [ 604800, 2592000, 7776000, 31536000, null ], "format": "int32", "type": [ "integer", "null" ] }, "clientType": { "type": "string" }, "consentSurface": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConsentSurface", "description": "Where this client's users grant consent. Omit for `hosted`, the page\ncore renders itself." } ] }, "description": { "type": [ "string", "null" ] }, "homepageUrl": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "name": { "$ref": "#/components/schemas/NonEmptyString" }, "redirectUris": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name", "clientType", "redirectUris" ], "type": "object" }, "CreatePodSecretPayload": { "properties": { "data": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "name", "data" ], "type": "object" }, "CreateProjectKeyParams": { "additionalProperties": false, "description": "Body for `POST\n/v1/management/organizations/{org_id}/projects/{project_id}/keys`.\n\nMints an additional regular project-scoped API key. The\n`connectionType` is always `api` for keys minted via the Management\nAPI surface and is set internally. The environment is inherited\nfrom the calling credential rather than being requested in the\nbody.", "properties": { "name": { "description": "Optional label for the new key (shown in the dashboard's API\nkeys list). When omitted, the key is unnamed.", "type": [ "string", "null" ] } }, "type": "object" }, "CreateProjectParams": { "additionalProperties": false, "description": "Body for `POST /v1/management/organizations/{org_id}/projects`.\n\nCreates a project under the given organization. Optionally mints a\nproject-scoped API key in the same call by setting `mintKey: true`\n\u2014 the key is returned in the response's `key` field. The new key\nis a regular API key (no `ServiceAccount` attribute), suitable for\ncustomer-facing application code; for further provisioning keep\nusing the org-level service-account key. The project itself is\nenvironment-agnostic; any key minted inherits its environment from\nthe caller's credential.", "properties": { "description": { "description": "Optional project description.", "type": [ "string", "null" ] }, "keyName": { "description": "Optional label for the new key. Only meaningful when `mintKey`\nis `true`; ignored otherwise. Validated in the handler when\n`mintKey` is `true` so callers that always submit an empty\n`keyName` without minting are not rejected.", "type": [ "string", "null" ] }, "mintKey": { "description": "When true, mint a project-scoped API key alongside the project\nand return it in the response. Defaults to false.", "type": "boolean" }, "name": { "description": "Human-readable project name.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateProjectResponse": { "description": "Response body for `POST\n/v1/management/organizations/{org_id}/projects`.\n\n`project` is always present. `key` is populated only when the\ncaller set `mintKey: true` in the request body; otherwise it is\n`null`.", "properties": { "key": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationEventAccessView", "description": "The freshly minted project-scoped API key, when `mintKey` was\nset to `true` in the request. `null` when the caller chose to\ncreate the project without a key (and will mint one later via\n`POST /organizations/{org_id}/projects/{project_id}/keys`). The\n`accessKey` field on the key, when present, is the only point\nat which the full secret is exposed." } ] }, "project": { "$ref": "#/components/schemas/ProjectView", "description": "The newly created project." } }, "required": [ "project" ], "type": "object" }, "CreateRelayAction": { "oneOf": [ { "properties": { "eventFilters": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "secret": { "type": [ "string", "null" ] }, "type": { "enum": [ "url" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "type" ], "type": "object" }, { "properties": { "actionId": { "type": "string" }, "body": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "connectionKey": { "type": "string" }, "eventFilters": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "headers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "query": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "type": { "enum": [ "passthrough" ], "type": "string" } }, "required": [ "connectionKey", "actionId", "type" ], "type": "object" }, { "properties": { "agentId": { "format": "uuid", "type": "string" }, "eventFilters": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "type": { "enum": [ "agent" ], "type": "string" } }, "required": [ "agentId", "type" ], "type": "object" } ] }, "CreateSubscriptionParams": { "properties": { "active": { "type": [ "boolean", "null" ] }, "description": { "type": [ "string", "null" ] }, "events": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "secret": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "url", "events" ], "type": "object" }, "DashboardPasswordView": { "description": "Response body for the dashboard-password reveal/regenerate routes: the\npod-owned credential the console displays. Both fields always present\n(framework-only routes).", "properties": { "dashboardPassword": { "type": "string" }, "dashboardUsername": { "type": "string" } }, "required": [ "dashboardUsername", "dashboardPassword" ], "type": "object" }, "EditParams": { "description": "The reach an edit is asking for, one entry per connected account.\n\nA total statement for every environment it names, not a diff: an account\nleft out of the list is one the app no longer reaches, and an account listed\nwith no `methods` or `actionIds` gets full access, up to the app's ask. An\nenvironment the list does not mention at all is left alone.", "properties": { "accessRules": { "items": { "$ref": "#/components/schemas/AccessRule" }, "type": "array" } }, "required": [ "accessRules" ], "type": "object" }, "EnvelopeView": { "description": "What a connector rule lets through, as every surface publishes it.\n\n**Absent means unrestricted, on the way out and on the way back in.** A\nsubmission that omits `methods` asks for *every* method, so a client offered\na narrowed connector sends this envelope back verbatim or its submission is\nrefused as widening - and \"copy what is there, omit what is not\" therefore\nproduces a valid submission in every case. Published without it, a narrowed\noffer was impossible to accept at all.\n\nOne type rather than one per surface: the held rule and the ask it is\nbounded by are the same envelope answering the same round-trip contract, and\ntwo definitions of it would eventually disagree.", "properties": { "allowedActions": { "description": "Resolved titles for the rule's `action_ids`, present only when the rule\nnarrows to a specific set (i.e. a custom rule). `None` means every\naction on the connector, which a customer-facing UI labels\ngenerically rather than listing.", "items": { "$ref": "#/components/schemas/AllowedActionView" }, "type": [ "array", "null" ] }, "methods": { "items": { "$ref": "#/components/schemas/Method" }, "type": [ "array", "null" ] } }, "type": "object" }, "ErrorResponse": { "properties": { "correlationId": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" }, "key": { "example": "http_error", "type": "string" }, "message": { "example": "Authentication required", "type": "string" }, "status": { "example": 401, "format": "int32", "minimum": 0, "type": "integer" }, "type": { "example": "http_error", "type": "string" } }, "required": [ "correlationId", "key", "message", "type", "status" ], "type": "object" }, "EventAccessId": { "description": "Prefixed ID with 'evt_ac' prefix (e.g., 'evt_ac_1C'), also accepts raw integer", "type": "string" }, "EventAccessView": { "properties": { "accessKey": { "type": "string" }, "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionType": { "$ref": "#/components/schemas/ConnectionType" }, "createdAt": { "format": "date-time", "type": "string" }, "default": { "type": "boolean" }, "deleted": { "type": "boolean" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "id": { "$ref": "#/components/schemas/EventAccessId" }, "key": { "type": "string" }, "keyPreview": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "throughput": { "format": "int32", "type": [ "integer", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "userId", "key", "connectionType", "accessKey", "environment", "default", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "FormDataItem": { "properties": { "label": { "type": "string" }, "name": { "type": "string" }, "optional": { "type": [ "boolean", "null" ] }, "options": { "items": { "$ref": "#/components/schemas/Value" }, "type": [ "array", "null" ] }, "placeholder": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type", "label", "placeholder" ], "type": "object" }, "GrantedAction": { "description": "One action a grant permits on a connection, resolved from an action id.", "properties": { "actionId": { "type": "string" }, "method": { "$ref": "#/components/schemas/Method" }, "title": { "type": "string" } }, "required": [ "actionId", "title", "method" ], "type": "object" }, "GrantedConnectionRuleView": { "allOf": [ { "$ref": "#/components/schemas/ResolvedConnectorView" }, { "properties": { "connectionKey": { "description": "The connection this rule was granted on, as `AccessRule::Connection`\nkeys it - so a resubmission names the same account rather than widening\nto its connector.", "type": "string" }, "offered": { "$ref": "#/components/schemas/EnvelopeView", "description": "What the app asked for on this connector, frozen at consent.\n\nThe ceiling an edit is checked against, published so a picker offers the\nlevels that will save rather than discovering the ceiling through a 403.\n`{}` is an app that asked for everything, which is also what an app that\nquoted no permission set asked for." } }, "required": [ "connectionKey", "offered" ], "type": "object" } ], "description": "One connection a grant names, with the rule stored for it. The connector\nhalf is [`ResolvedConnectorView`] flattened, so the envelope reads the same\neither way and is derived in one place." }, "GrantedConnectorView": { "description": "One connector an issued grant reaches, as an audit surface reports it.\n\n**Not [`ResolvedConnectorView`].** This is a read-only report, never fed\nback into a request: a dashboard folds every live token together, and the\nenvelopes of several grants on one connector do not combine into one, so a\nrule-shaped answer here would be a rule nobody granted.", "properties": { "actionCount": { "description": "Distinct actions reached across every grant and connection touching\nthis connector - the union, so a shared action counts once and disjoint\nones each.", "minimum": 0, "type": "integer" }, "connectionCount": { "description": "Distinct connections the grants name here. `None` when one of them\nnamed the *connector*, which reaches every connection on it including\nones added later, so no count would be true for long.", "minimum": 0, "type": [ "integer", "null" ] }, "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "imageUrl": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" } }, "required": [ "connectionDefinitionId", "name", "platform", "imageUrl", "actionCount" ], "type": "object" }, "HashAlgorithm": { "enum": [ "HMAC-SHA1", "HMAC-SHA256", "HMAC-SHA512", "PLAINTEXT" ], "type": "string" }, "HttpCreateCronRunParams": { "properties": { "completedAt": { "format": "date-time", "type": [ "string", "null" ] }, "durationMs": { "format": "int32", "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "responsePreview": { "type": [ "string", "null" ] }, "scheduledAt": { "format": "date-time", "type": "string" }, "startedAt": { "format": "date-time", "type": "string" }, "status": { "$ref": "#/components/schemas/AiAgentCronRunStatusType" } }, "required": [ "scheduledAt", "startedAt", "status" ], "type": "object" }, "InitResponse": { "allOf": [ { "$ref": "#/components/schemas/Paginated_ConnectedPlatformView" }, { "properties": { "requestId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthRequestId" } ] } }, "type": "object" } ] }, "InvitationActivity": { "oneOf": [ { "properties": { "at": { "format": "date-time", "type": "string" }, "kind": { "enum": [ "invitation_sent" ], "type": "string" } }, "required": [ "at", "kind" ], "type": "object" }, { "properties": { "at": { "format": "date-time", "type": "string" }, "kind": { "enum": [ "magic_link_resent" ], "type": "string" } }, "required": [ "at", "kind" ], "type": "object" }, { "properties": { "at": { "format": "date-time", "type": "string" }, "connection_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "customer_connected" ], "type": "string" }, "platform": { "type": "string" } }, "required": [ "at", "platform", "connection_id", "kind" ], "type": "object" }, { "properties": { "at": { "format": "date-time", "type": "string" }, "kind": { "enum": [ "invitation_accepted" ], "type": "string" } }, "required": [ "at", "kind" ], "type": "object" }, { "properties": { "at": { "format": "date-time", "type": "string" }, "kind": { "enum": [ "invitation_expired" ], "type": "string" } }, "required": [ "at", "kind" ], "type": "object" }, { "properties": { "at": { "format": "date-time", "type": "string" }, "by_user_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "api_key_rotated" ], "type": "string" } }, "required": [ "at", "by_user_id", "kind" ], "type": "object" } ] }, "InvitationView": { "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "organizationId": { "format": "uuid", "type": "string" }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "status": { "type": "string" } }, "required": [ "id", "organizationId", "email", "status" ], "type": "object" }, "JsonSchema": { "properties": { "inputSchema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "ioExample": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonSchemaExample" } ] }, "outputSchema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] } }, "type": "object" }, "JsonSchemaExample": { "properties": { "input": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] } }, "type": "object" }, "KnowledgeView": { "properties": { "_id": { "type": "string" }, "active": { "type": "boolean" }, "baseUrl": { "type": "string" }, "connectionPlatform": { "type": "string" }, "id": { "$ref": "#/components/schemas/ConnectionModelDefinitionId" }, "ioSchema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonSchema" } ] }, "knowledge": { "type": [ "string", "null" ] }, "method": { "$ref": "#/components/schemas/Method" }, "path": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "id", "_id", "connectionPlatform", "title", "path", "method", "baseUrl", "tags", "active" ], "type": "object" }, "LinkInvitationStatusType": { "enum": [ "pending", "accepted", "expired" ], "type": "string" }, "LinkInvitationView": { "properties": { "acceptedAt": { "format": "date-time", "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "activity": { "items": { "$ref": "#/components/schemas/InvitationActivity" }, "type": "array" }, "branding": { "$ref": "#/components/schemas/BrandingSnapshot" }, "connectorRules": { "items": { "$ref": "#/components/schemas/ConnectorRule" }, "type": "array" }, "createdAt": { "format": "date-time", "type": "string" }, "customerEmail": { "type": "string" }, "customerName": { "type": "string" }, "customerProjectId": { "format": "uuid", "type": "string" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "eventAccessId": { "$ref": "#/components/schemas/EventAccessId" }, "expiresAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "internalName": { "type": "string" }, "lastResendAt": { "format": "date-time", "type": [ "string", "null" ] }, "organizationId": { "format": "uuid", "type": "string" }, "status": { "$ref": "#/components/schemas/LinkInvitationStatusType" }, "templateId": { "format": "uuid", "type": "string" }, "templateProjectId": { "format": "uuid", "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "templateId", "organizationId", "customerProjectId", "eventAccessId", "customerName", "customerEmail", "internalName", "environment", "status", "expiresAt", "connectorRules", "branding", "activity", "createdAt", "updatedAt", "active" ], "type": "object" }, "LinkTemplateView": { "properties": { "active": { "type": "boolean" }, "connectorRules": { "items": { "$ref": "#/components/schemas/ConnectorRule" }, "type": "array" }, "createdAt": { "format": "date-time", "type": "string" }, "customerFacingName": { "type": "string" }, "darkLogoUrl": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "lightLogoUrl": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": "string" }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "successMessage": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "welcomeMessage": { "type": "string" } }, "required": [ "id", "organizationId", "name", "customerFacingName", "welcomeMessage", "successMessage", "connectorRules", "createdAt", "updatedAt", "active" ], "type": "object" }, "ManagementOrganizationMemberView": { "description": "Org-member row returned from the management API. Like the dashboard's\n`OrganizationMemberView` minus the internal `id` and `roleId` surrogate\nkeys (no management endpoint consumes them; they're an enumeration\nsidechannel and an `id` vs `userId` footgun). The dashboard view is\nunchanged.", "properties": { "joinedAt": { "format": "date-time", "type": "string" }, "roleKey": { "type": "string" }, "roleName": { "type": "string" }, "userEmail": { "type": "string" }, "userFirstName": { "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "userLastName": { "type": "string" }, "userUsername": { "type": "string" } }, "required": [ "userId", "roleKey", "roleName", "userEmail", "userFirstName", "userLastName", "userUsername", "joinedAt" ], "type": "object" }, "ManagementProjectMemberView": { "description": "Project-member row returned from the management API. Same omission\nrationale as [`ManagementOrganizationMemberView`].", "properties": { "joinedAt": { "format": "date-time", "type": "string" }, "roleKey": { "type": "string" }, "roleName": { "type": "string" }, "userEmail": { "type": "string" }, "userFirstName": { "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "userLastName": { "type": "string" }, "userUsername": { "type": "string" } }, "required": [ "userId", "roleKey", "roleName", "userEmail", "userFirstName", "userLastName", "userUsername", "joinedAt" ], "type": "object" }, "MarketplaceSkillView": { "allOf": [ { "$ref": "#/components/schemas/AiSkillVersionView" }, { "properties": { "organizationVerified": { "type": "boolean" } }, "required": [ "organizationVerified" ], "type": "object" } ] }, "MemberAddedPayload": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "organization_id": { "format": "uuid", "type": [ "string", "null" ] }, "organization_name": { "type": [ "string", "null" ] }, "project_id": { "format": "uuid", "type": [ "string", "null" ] }, "project_name": { "type": [ "string", "null" ] }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "email", "added_at" ], "type": "object" }, "MemberRemovedPayload": { "properties": { "email": { "type": "string" }, "organization_id": { "format": "uuid", "type": [ "string", "null" ] }, "organization_name": { "type": [ "string", "null" ] }, "project_id": { "format": "uuid", "type": [ "string", "null" ] }, "project_name": { "type": [ "string", "null" ] }, "removed_at": { "format": "date-time", "type": "string" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "email", "removed_at" ], "type": "object" }, "MemberRoleUpdatedPayload": { "properties": { "email": { "type": "string" }, "new_role": { "type": "string" }, "old_role": { "type": "string" }, "organization_id": { "format": "uuid", "type": [ "string", "null" ] }, "organization_name": { "type": [ "string", "null" ] }, "project_id": { "format": "uuid", "type": [ "string", "null" ] }, "project_name": { "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": "string" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "email", "old_role", "new_role", "updated_at" ], "type": "object" }, "Method": { "enum": [ "OPTIONS", "GET", "POST", "PUT", "DELETE", "HEAD", "TRACE", "CONNECT", "PATCH" ], "type": "string" }, "MetricBreakdown": { "properties": { "count": { "format": "int64", "minimum": 0, "type": "integer" }, "name": { "type": "string" }, "percentage": { "format": "double", "type": "number" } }, "required": [ "name", "count", "percentage" ], "type": "object" }, "NonEmptyString": { "type": "string" }, "OAuthAuthorizationView": { "description": "One app a user has granted access to, as their dashboard lists it.\n\nCore's response shape, not `common`'s: it names this service's consent\nvocabulary (`reach`) and nothing outside core reads it.", "properties": { "clientId": { "$ref": "#/components/schemas/OAuthClientId" }, "clientName": { "type": "string" }, "clientType": { "description": "Whether the app holds a secret. A public client is one that cannot, so\nthe pair says which kind of app the row is - the MCP clients that\nregister themselves and the OAuth apps a developer configured read\nidentically without it.", "type": "string" }, "consentSurface": { "$ref": "#/components/schemas/ConsentSurface", "description": "Where the app's users granted this: the page core renders, or the\nconnect card framed inside the app's own site." }, "createdAt": { "format": "date-time", "type": "string" }, "expiresAt": { "description": "When the app's current access token expires. `None` while the app holds\na live grant but no live token - the window between re-consent and\nthe client redeeming the new code.", "format": "date-time", "type": [ "string", "null" ] }, "homepageUrl": { "type": [ "string", "null" ] }, "lastUsedAt": { "format": "date-time", "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "reach": { "description": "What a grant reaches, generic over how each entry is rendered - the one\ntrichotomy two surfaces share: a dashboard reads it as counts\n([`GrantedReachView`]), a reconnect card as pre-selectable rules\n([`PriorGrantView`]). `KnowledgeOnly`/`Full` are identical on the wire for\nboth; only the `Connectors` element type differs.\n\nA bare generic derives a single schema named `ReachView`, so both\ninstantiations would collide on that one OpenAPI component and one endpoint\nwould advertise the other's connector shape. Every schema site that carries\none of these therefore inlines it (`#[schema(inline)]` / `inline(...)`), so\nno shared `ReachView` component exists to collide.", "oneOf": [ { "description": "Docs and search only: no connection access of any kind.", "properties": { "type": { "enum": [ "knowledgeOnly" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Every connection in the consented scope. No connector list because the\ngrant names none - it follows the account.", "properties": { "type": { "enum": [ "full" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Only what the grant names, each entry rendered as `C`. **The granularity\nis the instantiation's**: a reach report carries one entry per\nconnector, a prior grant one per granted *connection*, so two entries\nthere can share a connector.", "properties": { "connectors": { "items": { "$ref": "#/components/schemas/GrantedConnectorView" }, "type": "array" }, "type": { "enum": [ "connectors" ], "type": "string" } }, "required": [ "connectors", "type" ], "type": "object" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "tokenCount": { "minimum": 0, "type": "integer" } }, "required": [ "clientId", "clientName", "clientType", "consentSurface", "scopes", "reach", "createdAt", "tokenCount" ], "type": "object" }, "OAuthClientCreatedView": { "description": "View that includes the plain client secret - only used on creation", "properties": { "accessTokenTtl": { "format": "int32", "type": [ "integer", "null" ] }, "clientId": { "type": "string" }, "clientSecret": { "type": [ "string", "null" ] }, "clientType": { "type": "string" }, "consentSurface": { "$ref": "#/components/schemas/ConsentSurface" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "grantTypes": { "items": { "type": "string" }, "type": "array" }, "homepageUrl": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/OAuthClientId" }, "isActive": { "type": "boolean" }, "logoUrl": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "redirectUris": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "clientId", "name", "redirectUris", "clientType", "grantTypes", "isActive", "consentSurface", "createdAt" ], "type": "object" }, "OAuthClientId": { "description": "Prefixed ID with 'oac' prefix (e.g., 'oac_1C'), also accepts raw integer", "type": "string" }, "OAuthClientView": { "properties": { "accessTokenTtl": { "format": "int32", "type": [ "integer", "null" ] }, "clientId": { "type": "string" }, "clientType": { "type": "string" }, "consentSurface": { "$ref": "#/components/schemas/ConsentSurface" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "grantTypes": { "items": { "type": "string" }, "type": "array" }, "homepageUrl": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/OAuthClientId" }, "isActive": { "type": "boolean" }, "logoUrl": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "ownerId": { "format": "uuid", "type": "string" }, "redirectUris": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "clientId", "name", "redirectUris", "clientType", "grantTypes", "ownerId", "isActive", "consentSurface", "createdAt", "updatedAt" ], "type": "object" }, "OAuthFailedPayload": { "properties": { "connection_id": { "format": "uuid", "type": [ "string", "null" ] }, "error": { "type": "string" }, "failed_at": { "format": "date-time", "type": "string" }, "key": { "type": [ "string", "null" ] }, "platform": { "type": "string" } }, "required": [ "platform", "error", "failed_at" ], "type": "object", "x-one-connection-scoped": true }, "OAuthFlowType": { "enum": [ "authorization_code", "client_credentials", "refresh_token", "password", "implicit" ], "type": "string" }, "OAuthOverride": { "description": "A single override to apply to OAuth authorization URLs.\n\nStored as JSONB in `connection_oauth_definitions.configuration` as part\nof an `OAuthOverrides` list. Each variant drives a specific URL\ntransformation so the entire flow can be configured from the database.", "oneOf": [ { "description": "Rename query parameters. `params` maps original names to replacements\n(e.g. `{ \"client_id\": \"applicationId\" }`).", "properties": { "params": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "type": { "enum": [ "rename_param" ], "type": "string" } }, "required": [ "params", "type" ], "type": "object" }, { "description": "Remove query parameters by name.", "properties": { "params": { "items": { "type": "string" }, "type": "array" }, "type": { "enum": [ "remove_param" ], "type": "string" } }, "required": [ "params", "type" ], "type": "object" }, { "description": "Add extra query parameters. `params` maps names to values.", "properties": { "params": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "type": { "enum": [ "add_param" ], "type": "string" } }, "required": [ "params", "type" ], "type": "object" }, { "description": "Rewrite fragment-based OAuth authorization URLs (e.g. Xero-style\n`#/oauth/authorize?...` URLs).", "properties": { "type": { "enum": [ "fragment_rewrite" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Toggle PKCE on the authorization URL.\n`enabled: true` adds the challenge, `enabled: false` strips it.", "properties": { "enabled": { "type": "boolean" }, "type": { "enum": [ "pkce" ], "type": "string" } }, "required": [ "enabled", "type" ], "type": "object" }, { "description": "Bypass standard scope joining \u2014 append the scopes string as-is.", "properties": { "type": { "enum": [ "raw_scope" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ] }, "OAuthOverrides": { "description": "List of `OAuthOverride` entries stored as JSONB.", "items": { "$ref": "#/components/schemas/OAuthOverride" }, "type": "array" }, "OAuthPermissionSetView": { "description": "The wire shape of a permission set.\n\nLives here rather than beside the entity in `common`: it is the response\ncontract of core's `/v1/oauth-clients` routes and would make no sense\nwithout them, and a shared crate holds no one consumer's vocabulary. The\nentity and its store stay in `common`, where any service could reuse them.", "properties": { "active": { "type": "boolean" }, "clientId": { "description": "The owning client's public `client_id`, not the integer key: the key is\ninternal and the caller addresses the client by the string everywhere\nelse in `/v1/oauth-clients`.", "type": "string" }, "connectorRules": { "description": "The connectors this set grants, or `null` for the **allow-all** set,\nwhich grants every connector exactly as a ceremony naming no set does.\nThe same shape create accepts, so a fetched set round-trips.", "items": { "$ref": "#/components/schemas/ConnectorRule" }, "type": [ "array", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "clientId", "name", "createdAt", "updatedAt", "active" ], "type": "object" }, "OAuthRefreshedPayload": { "properties": { "connection_id": { "format": "uuid", "type": "string" }, "key": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "refreshed_at": { "format": "date-time", "type": "string" } }, "required": [ "connection_id", "platform", "refreshed_at" ], "type": "object", "x-one-connection-scoped": true }, "OAuthRequestId": { "description": "Prefixed ID with 'oauth_req' prefix (e.g., 'oauth_req_1C'), also accepts raw integer", "type": "string" }, "OAuthRevokeAuthorizationResponse": { "properties": { "accessTokens": { "format": "int64", "minimum": 0, "type": "integer" }, "refreshTokens": { "format": "int64", "minimum": 0, "type": "integer" }, "success": { "type": "boolean" } }, "required": [ "success", "accessTokens", "refreshTokens" ], "type": "object" }, "OAuthScopesView": { "description": "OAuth scope metadata for a connector, surfaced on the available-connectors\nlist only when the connector supports OAuth.", "properties": { "raw": { "description": "The exact scope string as stored, before splitting.", "type": "string" }, "scopes": { "description": "Individual OAuth scopes the connector requests.", "items": { "type": "string" }, "type": "array" }, "separator": { "description": "Delimiter used to join the scopes onto the provider authorization URL.\n`null` means the OAuth 2.0 default of a single space.", "type": [ "string", "null" ] } }, "required": [ "scopes", "raw" ], "type": "object" }, "OpenKnowledgeActionListItem": { "properties": { "id": { "type": "string" }, "method": { "$ref": "#/components/schemas/Method" }, "modelName": { "type": "string" }, "path": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "id", "title", "modelName", "method", "path", "tags" ], "type": "object" }, "OrganizationCreatedPayload": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name", "created_at" ], "type": "object" }, "OrganizationDeletedPayload": { "properties": { "deleted_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name", "deleted_at" ], "type": "object" }, "OrganizationEventAccessParams": { "properties": { "connectionType": { "$ref": "#/components/schemas/ConnectionType" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment", "description": "Required, and **ignored for a bearer**.\n\nA token is minted for one environment, so `pinned_environment`\nsubstitutes the token's own whatever the body says. Defaulting the\nfield would spare a bearer from sending a value it does not control,\nbut it would also stop a session or api-key caller from ever being told\nthey omitted it - and for those two the value is honoured, so a dropped\nor misspelled field would silently mint a `test` key for someone who\nasked for `live`. A loud `422` for the caller that does not care beats a\nsilent wrong key for the caller that does." }, "hide": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "tags": { "description": "Free-form labels stored on the key as sent: at most 32, each at\nmost 512 bytes. The CLI records where it is installed here\n(`scope:project`, `path:\u2026`, `harness:\u2026`). Omitted means no tags.", "items": { "type": "string" }, "type": "array" } }, "required": [ "connectionType", "environment" ], "type": "object" }, "OrganizationEventAccessView": { "description": "Organization-scoped event access view for API keys", "properties": { "accessKey": { "type": "string" }, "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionType": { "$ref": "#/components/schemas/ConnectionType" }, "createdAt": { "format": "date-time", "type": "string" }, "default": { "type": "boolean" }, "deleted": { "type": "boolean" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "id": { "$ref": "#/components/schemas/EventAccessId" }, "key": { "type": "string" }, "keyPreview": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "throughput": { "format": "int32", "type": [ "integer", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "userId", "key", "connectionType", "accessKey", "environment", "default", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "OrganizationMemberView": { "properties": { "id": { "format": "int32", "type": "integer" }, "joinedAt": { "format": "date-time", "type": "string" }, "roleId": { "format": "int32", "type": "integer" }, "roleKey": { "type": "string" }, "roleName": { "type": "string" }, "userEmail": { "type": "string" }, "userFirstName": { "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "userLastName": { "type": "string" }, "userUsername": { "type": "string" } }, "required": [ "id", "userId", "roleId", "roleKey", "roleName", "userEmail", "userFirstName", "userLastName", "userUsername", "joinedAt" ], "type": "object" }, "OrganizationSettingsView": { "properties": { "additionalAiAgentSeats": { "format": "int32", "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "createdBy": { "format": "uuid", "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "members": { "items": { "$ref": "#/components/schemas/OrganizationMemberView" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "format": "uuid", "type": "string" }, "pid": { "type": "string" }, "projects": { "items": { "$ref": "#/components/schemas/ProjectView" }, "type": "array" }, "slug": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "pid", "slug", "createdBy", "ownerId", "createdAt", "updatedAt", "additionalAiAgentSeats", "members", "projects" ], "type": "object" }, "OrganizationUpdatedPayload": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "updated_at" ], "type": "object" }, "OrganizationView": { "properties": { "additionalAiAgentSeats": { "format": "int32", "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "createdBy": { "format": "uuid", "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "ownerId": { "format": "uuid", "type": "string" }, "pid": { "type": "string" }, "rejectReason": { "type": [ "string", "null" ] }, "rejectedAt": { "format": "date-time", "type": [ "string", "null" ] }, "slug": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "verifiedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "name", "pid", "slug", "createdBy", "ownerId", "createdAt", "updatedAt", "additionalAiAgentSeats" ], "type": "object" }, "Page": { "properties": { "limit": { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "format": "int64", "minimum": 0, "type": "integer" }, "page": { "description": "Page number for pagination (1-indexed). Defaults to 1.", "format": "int64", "minimum": 0, "type": "integer" }, "skip": { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "format": "int64", "minimum": 0, "type": "integer" } }, "type": "object" }, "Paginated_AiSkillVersionView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "agent": { "type": [ "string", "null" ] }, "aiSkillId": { "$ref": "#/components/schemas/AiSkillId" }, "allowedTools": {}, "argumentHint": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "disableModelInvocation": { "type": "boolean" }, "hooks": {}, "id": { "$ref": "#/components/schemas/AiSkillVersionId" }, "model": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "publishedAt": { "format": "date-time", "type": "string" }, "publishedBy": { "format": "uuid", "type": "string" }, "rejectReason": { "type": [ "string", "null" ] }, "rejectedAt": { "format": "date-time", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "userInvocable": { "type": "boolean" }, "verifiedAt": { "format": "date-time", "type": [ "string", "null" ] }, "versionNumber": { "format": "int32", "type": "integer" }, "yankedAt": { "format": "date-time", "type": [ "string", "null" ] }, "yankedBy": { "format": "uuid", "type": [ "string", "null" ] }, "yankedReason": { "type": [ "string", "null" ] } }, "required": [ "id", "aiSkillId", "versionNumber", "name", "description", "content", "disableModelInvocation", "userInvocable", "tags", "publishedAt", "publishedBy" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_AiSkillView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "agent": { "type": [ "string", "null" ] }, "allowedTools": {}, "argumentHint": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "disableModelInvocation": { "type": "boolean" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "hooks": {}, "id": { "$ref": "#/components/schemas/AiSkillId" }, "lastUsedAt": { "format": "date-time", "type": [ "string", "null" ] }, "latestPublishedVersionId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiSkillVersionId" } ] }, "model": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "public": { "type": "boolean" }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "usageCount": { "format": "int32", "type": "integer" }, "userId": { "format": "uuid", "type": "string" }, "userInvocable": { "type": "boolean" }, "version": { "type": "string" } }, "required": [ "id", "userId", "name", "description", "content", "disableModelInvocation", "userInvocable", "environment", "usageCount", "createdAt", "updatedAt", "version", "tags", "active", "public" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_AvailableActionsView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "key": { "type": "string" }, "method": { "$ref": "#/components/schemas/Method" }, "modelName": { "type": "string" }, "path": { "type": "string" }, "systemId": { "description": "Stable id for this action. Use as `actionId` for passthrough /\nexecute calls; survives renames of `key` or `title`.", "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "systemId", "title", "key", "modelName", "method", "path", "tags" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_AvailableConnectorView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "category": { "type": "string" }, "description": { "type": "string" }, "id": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "image": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "oauth": { "type": "boolean" }, "oauthScopes": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthScopesView" } ] }, "platform": { "type": "string" }, "platformVersion": { "type": "string" }, "status": { "$ref": "#/components/schemas/ConnectionStatusType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": [ "string", "null" ] }, "tools": { "format": "int32", "type": "integer" }, "version": { "type": "string" } }, "required": [ "id", "name", "platformVersion", "status", "key", "platform", "description", "category", "image", "tags", "tools", "oauth", "version", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_CeremonyConnectionView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "description": "One connection the card may be told about: enough to mark a connector as\nalready connected, and nothing more.\n\n**Not `ConnectionView`.** That carries `secret_id`, `webhook_secret_id`,\n`identity`, the owning `user_id` and the whole `change_log` - none of which\na consent screen needs, and all of which would be handed to a surface whose\nentire job is to be embedded in somebody else's page. What stays is what the\ncard acts on: which connector, which connection, and whether it is healthy.", "properties": { "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId", "description": "Which connector, so the card can match it against the ceremony's offer." }, "key": { "description": "The connection's public key, and the reason this view is not narrower\nstill: a restricted consent names a connection through\n`AccessRule::Connection`, which is keyed on exactly this. Without it a\ncard that wants to include a connection the user already has cannot\nname it, and has to fall back to a connector-wide grant - so omitting\nit made the resulting grant *wider*, not tighter.", "type": "string" }, "name": { "description": "The user's own label for it, when they gave one.", "type": [ "string", "null" ] }, "platform": { "type": "string" }, "state": { "$ref": "#/components/schemas/ConnectionStateType" }, "tags": { "description": "The user's own tags, so the card can tell two accounts on one connector\napart at a glance. Empty when they tagged it with none.", "items": { "type": "string" }, "type": "array" } }, "required": [ "connectionDefinitionId", "key", "platform", "state", "tags" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_ClientUserView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "description": "One user's standing with an OAuth client, as its developer sees them.\n\nCarries `reach` in the same consent vocabulary as\n[`crate::domain::oauth_authorization::OAuthAuthorizationView`], so the two\nsides of the ledger report a grant identically.", "properties": { "createdAt": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "expiresAt": { "description": "When the user's current access token for this client expires. `None`\nwhile they hold a live grant but no live token - the window between\nre-consent and the client redeeming the new code.", "format": "date-time", "type": [ "string", "null" ] }, "lastUsedAt": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "reach": { "description": "What a grant reaches, generic over how each entry is rendered - the one\ntrichotomy two surfaces share: a dashboard reads it as counts\n([`GrantedReachView`]), a reconnect card as pre-selectable rules\n([`PriorGrantView`]). `KnowledgeOnly`/`Full` are identical on the wire for\nboth; only the `Connectors` element type differs.\n\nA bare generic derives a single schema named `ReachView`, so both\ninstantiations would collide on that one OpenAPI component and one endpoint\nwould advertise the other's connector shape. Every schema site that carries\none of these therefore inlines it (`#[schema(inline)]` / `inline(...)`), so\nno shared `ReachView` component exists to collide.", "oneOf": [ { "description": "Docs and search only: no connection access of any kind.", "properties": { "type": { "enum": [ "knowledgeOnly" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Every connection in the consented scope. No connector list because the\ngrant names none - it follows the account.", "properties": { "type": { "enum": [ "full" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Only what the grant names, each entry rendered as `C`. **The granularity\nis the instantiation's**: a reach report carries one entry per\nconnector, a prior grant one per granted *connection*, so two entries\nthere can share a connector.", "properties": { "connectors": { "items": { "$ref": "#/components/schemas/GrantedConnectorView" }, "type": "array" }, "type": { "enum": [ "connectors" ], "type": "string" } }, "required": [ "connectors", "type" ], "type": "object" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "tokenCount": { "minimum": 0, "type": "integer" }, "userId": { "format": "uuid", "type": "string" }, "username": { "type": "string" } }, "required": [ "userId", "email", "username", "scopes", "reach", "createdAt", "tokenCount" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_ConnectedPlatformView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "activatedAt": { "format": "date-time", "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "clientIdDisplay": { "type": [ "string", "null" ] }, "clientSecretDisplay": { "type": [ "string", "null" ] }, "connectionDefId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "createdAt": { "format": "date-time", "type": "string" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "guide": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/ConnectedPlatformId" }, "image": { "type": "string" }, "scopes": { "type": [ "string", "null" ] }, "secretId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "type": { "type": "string" }, "useDefaultOauthCreds": { "type": "boolean" } }, "required": [ "id", "connectionDefId", "type", "title", "image", "environment", "createdAt", "tags", "active", "useDefaultOauthCreds" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_ConnectionDefinitionView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "_id": { "format": "int32", "type": "integer" }, "active": { "type": "boolean" }, "authMethod": { "$ref": "#/components/schemas/AuthMethodView" }, "authSecrets": { "items": { "type": "string" }, "type": "array" }, "authentication": { "type": [ "string", "null" ] }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "frontend": { "$ref": "#/components/schemas/ConnectionDefinitionFrontend" }, "id": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "key": { "type": "string" }, "name": { "type": "string" }, "oauth": { "type": "boolean" }, "platform": { "type": "string" }, "platformVersion": { "type": "string" }, "status": { "$ref": "#/components/schemas/ConnectionStatusType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "type": { "$ref": "#/components/schemas/ConnectionType" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "_id", "platformVersion", "platform", "status", "key", "type", "authMethod", "name", "authSecrets", "frontend", "oauth", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_ConnectionOAuthDefinitionView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "configuration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthOverrides" } ] }, "connectionDefId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "connectionPlatform": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "flowType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthFlowType" } ] }, "frontend": { "$ref": "#/components/schemas/ConnectionOAuthDefinitionFrontend" }, "id": { "$ref": "#/components/schemas/ConnectionOAuthDefinitionId" }, "renderWithSecret": { "type": "boolean" }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "connectionDefId", "connectionPlatform", "frontend", "renderWithSecret", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_ConnectionView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "connectionOauthDefId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionOAuthDefinitionId" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "expiresAt": { "format": "date-time", "type": [ "string", "null" ] }, "expiresIn": { "format": "int64", "type": [ "integer", "null" ] }, "group": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "identity": { "type": [ "string", "null" ] }, "identityType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionIdentityType" } ] }, "image": { "type": [ "string", "null" ] }, "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "platformVersion": { "type": "string" }, "secretId": { "format": "uuid", "type": "string" }, "state": { "$ref": "#/components/schemas/ConnectionStateType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/ConnectionType" }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" }, "webhookSecretId": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "id", "platformVersion", "connectionDefinitionId", "type", "group", "key", "environment", "platform", "secretId", "state", "userId", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_EventAccessView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "accessKey": { "type": "string" }, "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionType": { "$ref": "#/components/schemas/ConnectionType" }, "createdAt": { "format": "date-time", "type": "string" }, "default": { "type": "boolean" }, "deleted": { "type": "boolean" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "id": { "$ref": "#/components/schemas/EventAccessId" }, "key": { "type": "string" }, "keyPreview": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "throughput": { "format": "int32", "type": [ "integer", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "userId", "key", "connectionType", "accessKey", "environment", "default", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_InvitationView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "organizationId": { "format": "uuid", "type": "string" }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "status": { "type": "string" } }, "required": [ "id", "organizationId", "email", "status" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_KnowledgeView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "_id": { "type": "string" }, "active": { "type": "boolean" }, "baseUrl": { "type": "string" }, "connectionPlatform": { "type": "string" }, "id": { "$ref": "#/components/schemas/ConnectionModelDefinitionId" }, "ioSchema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonSchema" } ] }, "knowledge": { "type": [ "string", "null" ] }, "method": { "$ref": "#/components/schemas/Method" }, "path": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "id", "_id", "connectionPlatform", "title", "path", "method", "baseUrl", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_LinkInvitationView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "acceptedAt": { "format": "date-time", "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "activity": { "items": { "$ref": "#/components/schemas/InvitationActivity" }, "type": "array" }, "branding": { "$ref": "#/components/schemas/BrandingSnapshot" }, "connectorRules": { "items": { "$ref": "#/components/schemas/ConnectorRule" }, "type": "array" }, "createdAt": { "format": "date-time", "type": "string" }, "customerEmail": { "type": "string" }, "customerName": { "type": "string" }, "customerProjectId": { "format": "uuid", "type": "string" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "eventAccessId": { "$ref": "#/components/schemas/EventAccessId" }, "expiresAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "internalName": { "type": "string" }, "lastResendAt": { "format": "date-time", "type": [ "string", "null" ] }, "organizationId": { "format": "uuid", "type": "string" }, "status": { "$ref": "#/components/schemas/LinkInvitationStatusType" }, "templateId": { "format": "uuid", "type": "string" }, "templateProjectId": { "format": "uuid", "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "templateId", "organizationId", "customerProjectId", "eventAccessId", "customerName", "customerEmail", "internalName", "environment", "status", "expiresAt", "connectorRules", "branding", "activity", "createdAt", "updatedAt", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_LinkTemplateView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "connectorRules": { "items": { "$ref": "#/components/schemas/ConnectorRule" }, "type": "array" }, "createdAt": { "format": "date-time", "type": "string" }, "customerFacingName": { "type": "string" }, "darkLogoUrl": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "lightLogoUrl": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": "string" }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "successMessage": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "welcomeMessage": { "type": "string" } }, "required": [ "id", "organizationId", "name", "customerFacingName", "welcomeMessage", "successMessage", "connectorRules", "createdAt", "updatedAt", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_ManagementOrganizationMemberView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "description": "Org-member row returned from the management API. Like the dashboard's\n`OrganizationMemberView` minus the internal `id` and `roleId` surrogate\nkeys (no management endpoint consumes them; they're an enumeration\nsidechannel and an `id` vs `userId` footgun). The dashboard view is\nunchanged.", "properties": { "joinedAt": { "format": "date-time", "type": "string" }, "roleKey": { "type": "string" }, "roleName": { "type": "string" }, "userEmail": { "type": "string" }, "userFirstName": { "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "userLastName": { "type": "string" }, "userUsername": { "type": "string" } }, "required": [ "userId", "roleKey", "roleName", "userEmail", "userFirstName", "userLastName", "userUsername", "joinedAt" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_ManagementProjectMemberView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "description": "Project-member row returned from the management API. Same omission\nrationale as [`ManagementOrganizationMemberView`].", "properties": { "joinedAt": { "format": "date-time", "type": "string" }, "roleKey": { "type": "string" }, "roleName": { "type": "string" }, "userEmail": { "type": "string" }, "userFirstName": { "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "userLastName": { "type": "string" }, "userUsername": { "type": "string" } }, "required": [ "userId", "roleKey", "roleName", "userEmail", "userFirstName", "userLastName", "userUsername", "joinedAt" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_MarketplaceSkillView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "allOf": [ { "$ref": "#/components/schemas/AiSkillVersionView" }, { "properties": { "organizationVerified": { "type": "boolean" } }, "required": [ "organizationVerified" ], "type": "object" } ] }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_OAuthAuthorizationView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "description": "One app a user has granted access to, as their dashboard lists it.\n\nCore's response shape, not `common`'s: it names this service's consent\nvocabulary (`reach`) and nothing outside core reads it.", "properties": { "clientId": { "$ref": "#/components/schemas/OAuthClientId" }, "clientName": { "type": "string" }, "clientType": { "description": "Whether the app holds a secret. A public client is one that cannot, so\nthe pair says which kind of app the row is - the MCP clients that\nregister themselves and the OAuth apps a developer configured read\nidentically without it.", "type": "string" }, "consentSurface": { "$ref": "#/components/schemas/ConsentSurface", "description": "Where the app's users granted this: the page core renders, or the\nconnect card framed inside the app's own site." }, "createdAt": { "format": "date-time", "type": "string" }, "expiresAt": { "description": "When the app's current access token expires. `None` while the app holds\na live grant but no live token - the window between re-consent and\nthe client redeeming the new code.", "format": "date-time", "type": [ "string", "null" ] }, "homepageUrl": { "type": [ "string", "null" ] }, "lastUsedAt": { "format": "date-time", "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "reach": { "description": "What a grant reaches, generic over how each entry is rendered - the one\ntrichotomy two surfaces share: a dashboard reads it as counts\n([`GrantedReachView`]), a reconnect card as pre-selectable rules\n([`PriorGrantView`]). `KnowledgeOnly`/`Full` are identical on the wire for\nboth; only the `Connectors` element type differs.\n\nA bare generic derives a single schema named `ReachView`, so both\ninstantiations would collide on that one OpenAPI component and one endpoint\nwould advertise the other's connector shape. Every schema site that carries\none of these therefore inlines it (`#[schema(inline)]` / `inline(...)`), so\nno shared `ReachView` component exists to collide.", "oneOf": [ { "description": "Docs and search only: no connection access of any kind.", "properties": { "type": { "enum": [ "knowledgeOnly" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Every connection in the consented scope. No connector list because the\ngrant names none - it follows the account.", "properties": { "type": { "enum": [ "full" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Only what the grant names, each entry rendered as `C`. **The granularity\nis the instantiation's**: a reach report carries one entry per\nconnector, a prior grant one per granted *connection*, so two entries\nthere can share a connector.", "properties": { "connectors": { "items": { "$ref": "#/components/schemas/GrantedConnectorView" }, "type": "array" }, "type": { "enum": [ "connectors" ], "type": "string" } }, "required": [ "connectors", "type" ], "type": "object" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "tokenCount": { "minimum": 0, "type": "integer" } }, "required": [ "clientId", "clientName", "clientType", "consentSurface", "scopes", "reach", "createdAt", "tokenCount" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_OAuthClientView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "accessTokenTtl": { "format": "int32", "type": [ "integer", "null" ] }, "clientId": { "type": "string" }, "clientType": { "type": "string" }, "consentSurface": { "$ref": "#/components/schemas/ConsentSurface" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "grantTypes": { "items": { "type": "string" }, "type": "array" }, "homepageUrl": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/OAuthClientId" }, "isActive": { "type": "boolean" }, "logoUrl": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "ownerId": { "format": "uuid", "type": "string" }, "redirectUris": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "clientId", "name", "redirectUris", "clientType", "grantTypes", "ownerId", "isActive", "consentSurface", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_OAuthPermissionSetView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "description": "The wire shape of a permission set.\n\nLives here rather than beside the entity in `common`: it is the response\ncontract of core's `/v1/oauth-clients` routes and would make no sense\nwithout them, and a shared crate holds no one consumer's vocabulary. The\nentity and its store stay in `common`, where any service could reuse them.", "properties": { "active": { "type": "boolean" }, "clientId": { "description": "The owning client's public `client_id`, not the integer key: the key is\ninternal and the caller addresses the client by the string everywhere\nelse in `/v1/oauth-clients`.", "type": "string" }, "connectorRules": { "description": "The connectors this set grants, or `null` for the **allow-all** set,\nwhich grants every connector exactly as a ceremony naming no set does.\nThe same shape create accepts, so a fetched set round-trips.", "items": { "$ref": "#/components/schemas/ConnectorRule" }, "type": [ "array", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "clientId", "name", "createdAt", "updatedAt", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_OpenKnowledgeActionListItem": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "id": { "type": "string" }, "method": { "$ref": "#/components/schemas/Method" }, "modelName": { "type": "string" }, "path": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "id", "title", "modelName", "method", "path", "tags" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_OrganizationEventAccessView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "description": "Organization-scoped event access view for API keys", "properties": { "accessKey": { "type": "string" }, "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionType": { "$ref": "#/components/schemas/ConnectionType" }, "createdAt": { "format": "date-time", "type": "string" }, "default": { "type": "boolean" }, "deleted": { "type": "boolean" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "id": { "$ref": "#/components/schemas/EventAccessId" }, "key": { "type": "string" }, "keyPreview": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "throughput": { "format": "int32", "type": [ "integer", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "userId", "key", "connectionType", "accessKey", "environment", "default", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_ProjectView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "additionalAiAgentSeats": { "format": "int32", "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "createdBy": { "format": "uuid", "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": "string" }, "ownerId": { "format": "uuid", "type": "string" }, "pid": { "type": "string" }, "slug": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "name", "pid", "slug", "createdBy", "ownerId", "createdAt", "updatedAt", "additionalAiAgentSeats" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_ReachableConnectionView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "description": "A connection as a grant *reaches* it, for the grant-scoped reachable\nlisting.\n\nDeliberately narrow: the key a granted app connects with, the connector and\ndisplay it needs to render a tile, and the [`ConnectionAccess`] it may run -\nand nothing else. It carries no row id, no `identity`, `secret_id` or\n`user_id`, not even the environment (the key already encodes it) or the\nactive flag (only active rows are listed), so a grant that can only run an\naction on a connection learns no more than its key - exactly what the\nreadable listing and the single retrieve withhold from an action grant. The\nmanagement [`ConnectionView`] is untouched.", "properties": { "access": { "$ref": "#/components/schemas/ConnectionAccess" }, "connector": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "title": { "type": [ "string", "null" ] } }, "required": [ "key", "connector", "platform", "access" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_VaultConnectionView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "connector": { "description": "The connector behind this connection. Carried because a grant bounded\nby connectors decides on it, so a caller rendering what a token may do\nhere would otherwise have to resolve it by a second lookup per row.", "type": "string" }, "description": { "type": "string" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "id": { "format": "uuid", "type": "string" }, "identity": { "type": [ "string", "null" ] }, "identityType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionIdentityType" } ] }, "image": { "type": "string" }, "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "platformVersion": { "type": "string" }, "state": { "$ref": "#/components/schemas/ConnectionStateType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/ConnectionType" }, "version": { "type": "string" } }, "required": [ "id", "connector", "platformVersion", "type", "key", "environment", "platform", "description", "image", "version", "state", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_WebhookEventView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "eventType": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "metadata": { "$ref": "#/components/schemas/Value" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "payload": { "$ref": "#/components/schemas/Value" }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "timestamp": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "eventType", "payload", "timestamp", "metadata", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_WebhookRelayEndpointView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/RelayActionView" }, "type": "array" }, "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionId": { "format": "uuid", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "eventFilters": { "items": { "type": "string" }, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "url": { "type": [ "string", "null" ] }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" }, "warning": { "type": [ "string", "null" ] }, "webhookPayload": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] } }, "required": [ "id", "connectionId", "userId", "actions", "eventFilters", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_WebhookRelayEventView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionId": { "format": "uuid", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "eventType": { "type": [ "string", "null" ] }, "headers": { "$ref": "#/components/schemas/Value" }, "id": { "format": "uuid", "type": "string" }, "metadata": { "$ref": "#/components/schemas/Value" }, "payload": { "$ref": "#/components/schemas/Value" }, "platform": { "type": "string" }, "signatureValid": { "type": [ "boolean", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "timestamp": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "connectionId", "userId", "platform", "headers", "payload", "timestamp", "metadata", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Paginated_WebhookSubscriptionView": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "events": { "items": { "type": "string" }, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "key": { "type": "string" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "url": { "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "userId", "url", "key", "events", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" }, "Params": { "properties": { "active": { "type": "boolean" }, "clientId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NonEmptyString" } ] }, "clientSecret": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NonEmptyString" } ] }, "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "guide": { "type": [ "string", "null" ] }, "scopes": { "type": [ "string", "null" ] }, "useDefaultOauthCreds": { "description": "When true, uses default OAuth credentials from the engineering account\ninstead of user-provided credentials. See the struct-level\ndocumentation for detailed precedence behavior and requirements.", "type": [ "boolean", "null" ] } }, "required": [ "connectionDefinitionId", "environment", "active" ], "type": "object" }, "PassthroughExecutedPayload": { "properties": { "connection_id": { "format": "uuid", "type": "string" }, "duration_ms": { "format": "int64", "type": "integer" }, "error": { "type": [ "string", "null" ] }, "key": { "type": [ "string", "null" ] }, "method": { "type": "string" }, "path": { "type": "string" }, "platform": { "type": "string" }, "status_code": { "format": "int32", "minimum": 0, "type": [ "integer", "null" ] }, "timestamp": { "format": "date-time", "type": "string" } }, "required": [ "connection_id", "platform", "method", "path", "duration_ms", "timestamp" ], "type": "object", "x-one-connection-scoped": true }, "PermissionSetBody": { "properties": { "connectorRules": { "description": "The connectors this set grants. `null` (or omitted) creates the\n**allow-all** set, which grants every connector - the named,\nreferenceable equivalent of authorizing with no set at all.", "items": { "$ref": "#/components/schemas/ConnectorRule" }, "type": [ "array", "null" ] }, "name": { "$ref": "#/components/schemas/NonEmptyString" } }, "required": [ "name" ], "type": "object" }, "PermissionSetDetailView": { "allOf": [ { "$ref": "#/components/schemas/OAuthPermissionSetView" }, { "properties": { "connectors": { "items": { "$ref": "#/components/schemas/ResolvedConnectorView" }, "type": "array" } }, "required": [ "connectors" ], "type": "object" } ], "description": "A set plus its rules resolved against the connector catalog.\n\nResolution is offered on the single-set reads only. A page of sets would\nmean one catalog round-trip per rule per set, and the collection view has\nno use for connector logos - the set's own name is what a picker shows." }, "PodSecretView": { "properties": { "active": { "type": "boolean" }, "agentId": { "format": "uuid", "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "k8sNamespace": { "type": "string" }, "k8sSecretName": { "type": "string" }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "userId", "name", "k8sSecretName", "k8sNamespace", "createdAt", "updatedAt", "version", "tags", "active" ], "type": "object" }, "PodStatusType": { "enum": [ "pending", "running", "succeeded", "failed", "terminated" ], "type": "string" }, "PodStopReasonType": { "description": "Why a pod was stopped. The same operation reached two ways, and the\ndifference matters after the fact: a user pausing their runner and billing\nculling it for a lapsed seat leave an identical `terminated` row, and mean\ncompletely different things to whoever is asking why an agent went quiet -\none is \"I did that\", the other is \"resume will not help until you pay\".\n\nNull on a pod that has not been stopped, and on rows written before this was\nrecorded.\n\nDeliberately has no `Default`. \"Why did this stop\" has no sensible fallback:\nthe column is nullable precisely because *unknown* is the honest answer for\na pod stopped before it existed, and any default would answer that question\nwith a guess. `user_requested` in particular is the one value that makes a\nconsole offer a restart.", "enum": [ "user_requested", "seat_lapsed" ], "type": "string" }, "PodView": { "properties": { "active": { "type": "boolean" }, "args": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "command": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "envVars": {}, "finishedAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "idleTimeoutMs": { "format": "int64", "type": "integer" }, "image": { "type": "string" }, "k8sNamespace": { "type": "string" }, "k8sPodIp": { "type": [ "string", "null" ] }, "k8sPodName": { "type": "string" }, "k8sPort": { "format": "int32", "type": "integer" }, "k8sSubdomain": { "type": "string" }, "labels": {}, "lastActivityAt": { "format": "date-time", "type": "string" }, "maxLifetimeMs": { "format": "int64", "type": "integer" }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "resources": {}, "runtime": { "$ref": "#/components/schemas/AiRuntimeType" }, "secretRefs": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "startedAt": { "format": "date-time", "type": "string" }, "status": { "$ref": "#/components/schemas/PodStatusType" }, "stopReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PodStopReasonType", "description": "What stopped this pod, when it is stopped. A cause, not a prediction:\nsee `AiAgentView::runner_stop_reason`, which surfaces the same value on\nan agent read." } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" }, "volumeMountPath": { "type": "string" }, "volumeSize": { "type": "string" } }, "required": [ "id", "userId", "name", "image", "status", "k8sNamespace", "k8sPodName", "k8sSubdomain", "k8sPort", "runtime", "resources", "envVars", "secretRefs", "volumeMountPath", "volumeSize", "labels", "lastActivityAt", "idleTimeoutMs", "maxLifetimeMs", "startedAt", "finishedAt", "createdAt", "updatedAt", "version", "tags", "active" ], "type": "object" }, "PrepareInitParams": { "properties": { "group": { "type": [ "string", "null" ] }, "identity": { "type": [ "string", "null" ] }, "identityType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionIdentityType" } ] }, "label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "ProjectCreatedPayload": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "organization_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "name", "organization_id", "created_at" ], "type": "object" }, "ProjectDeletedPayload": { "properties": { "deleted_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "organization_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "name", "organization_id", "deleted_at" ], "type": "object" }, "ProjectUpdatedPayload": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "organization_id", "updated_at" ], "type": "object" }, "ProjectView": { "properties": { "additionalAiAgentSeats": { "format": "int32", "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "createdBy": { "format": "uuid", "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": "string" }, "ownerId": { "format": "uuid", "type": "string" }, "pid": { "type": "string" }, "slug": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "name", "pid", "slug", "createdBy", "ownerId", "createdAt", "updatedAt", "additionalAiAgentSeats" ], "type": "object" }, "ReachableConnectionView": { "description": "A connection as a grant *reaches* it, for the grant-scoped reachable\nlisting.\n\nDeliberately narrow: the key a granted app connects with, the connector and\ndisplay it needs to render a tile, and the [`ConnectionAccess`] it may run -\nand nothing else. It carries no row id, no `identity`, `secret_id` or\n`user_id`, not even the environment (the key already encodes it) or the\nactive flag (only active rows are listed), so a grant that can only run an\naction on a connection learns no more than its key - exactly what the\nreadable listing and the single retrieve withhold from an action grant. The\nmanagement [`ConnectionView`] is untouched.", "properties": { "access": { "$ref": "#/components/schemas/ConnectionAccess" }, "connector": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "title": { "type": [ "string", "null" ] } }, "required": [ "key", "connector", "platform", "access" ], "type": "object" }, "RelayActionView": { "oneOf": [ { "properties": { "eventFilters": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "hasSecret": { "type": "boolean" }, "type": { "enum": [ "url" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "hasSecret", "type" ], "type": "object" }, { "properties": { "actionId": { "type": "string" }, "body": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "connectionKey": { "type": "string" }, "eventFilters": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "headers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "query": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "type": { "enum": [ "passthrough" ], "type": "string" } }, "required": [ "connectionKey", "actionId", "type" ], "type": "object" }, { "properties": { "agentId": { "format": "uuid", "type": "string" }, "eventFilters": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "type": { "enum": [ "agent" ], "type": "string" } }, "required": [ "agentId", "type" ], "type": "object" } ] }, "RelayDeliveryView": { "properties": { "actionIndex": { "format": "int32", "type": "integer" }, "attempt": { "format": "int32", "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "deliveredAt": { "format": "date-time", "type": [ "string", "null" ] }, "endpointId": { "format": "uuid", "type": "string" }, "error": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "relayEventId": { "format": "uuid", "type": "string" }, "responseBody": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "statusCode": { "format": "int32", "type": [ "integer", "null" ] } }, "required": [ "id", "relayEventId", "endpointId", "actionIndex", "status", "attempt", "createdAt" ], "type": "object" }, "RemoveMemberResponse": { "properties": { "message": { "type": "string" }, "organizationId": { "format": "uuid", "type": "string" }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "userId": { "format": "uuid", "type": "string" } }, "required": [ "message", "userId", "organizationId" ], "type": "object" }, "ResolveResponse": { "properties": { "connectors": { "items": { "$ref": "#/components/schemas/ResolvedConnectorView" }, "type": "array" }, "invitation": { "$ref": "#/components/schemas/LinkInvitationView" } }, "required": [ "invitation", "connectors" ], "type": "object" }, "ResolvedConnectorView": { "allOf": [ { "$ref": "#/components/schemas/EnvelopeView" }, { "properties": { "actionCount": { "minimum": 0, "type": "integer" }, "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "imageUrl": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" } }, "required": [ "connectionDefinitionId", "name", "platform", "imageUrl", "actionCount" ], "type": "object" } ] }, "RetrieveResponse": { "description": "Retrieve response surfaces the invitation alongside the\n`connected_platforms` rows currently activated in the customer_project.\nCloses the agency's visibility gap into auto-activation results \u2014 without\nthis they have no read path to \"did activation actually land for this\ninvitation.\"", "properties": { "activatedConnectors": { "$ref": "#/components/schemas/Paginated_ConnectedPlatformView" }, "invitation": { "$ref": "#/components/schemas/LinkInvitationView" } }, "required": [ "invitation", "activatedConnectors" ], "type": "object" }, "RoleHierarchy": { "description": "Role hierarchy enum representing the different organizational roles", "enum": [ "Member", "Manager", "Admin" ], "type": "string" }, "RotateResponse": { "properties": { "apiKey": { "type": "string" } }, "required": [ "apiKey" ], "type": "object" }, "RuleResponse": { "oneOf": [ { "properties": { "actionIds": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "connectionKey": { "type": "string" }, "methods": { "items": { "$ref": "#/components/schemas/Method" }, "type": [ "array", "null" ] }, "type": { "enum": [ "connection" ], "type": "string" } }, "required": [ "connectionKey", "type" ], "type": "object" }, { "properties": { "actionIds": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "methods": { "items": { "$ref": "#/components/schemas/Method" }, "type": [ "array", "null" ] }, "type": { "enum": [ "connectionDefinition" ], "type": "string" } }, "required": [ "connectionDefinitionId", "type" ], "type": "object" } ] }, "SecretKeyEnvironment": { "enum": [ "test", "live" ], "type": "string" }, "SecretView": { "properties": { "clientId": { "type": "string" }, "clientSecret": { "type": "string" } }, "required": [ "clientId", "clientSecret" ], "type": "object" }, "SendBody": { "properties": { "customerEmail": { "$ref": "#/components/schemas/NonEmptyString" }, "customerName": { "$ref": "#/components/schemas/NonEmptyString" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "internalName": { "$ref": "#/components/schemas/NonEmptyString" }, "templateId": { "format": "uuid", "type": "string" } }, "required": [ "templateId", "customerName", "customerEmail", "internalName", "environment" ], "type": "object" }, "SendResponse": { "allOf": [ { "$ref": "#/components/schemas/LinkInvitationView" }, { "properties": { "apiKey": { "type": "string" } }, "required": [ "apiKey" ], "type": "object" } ] }, "SetupOrganizationParams": { "additionalProperties": false, "description": "Request body for `POST /v1/management/organizations/setup`.\n\nCreates an organization and mints its first service-account API key in\none call. The organization itself is environment-agnostic; the new\nkey inherits its environment from the calling credential (the\nsecret-key the caller used, or the session's `x-pica-environment`\nheader).", "properties": { "description": { "description": "Optional organization description.", "type": [ "string", "null" ] }, "keyName": { "description": "Optional label for the new key (shown in the dashboard's API keys\nlist). When omitted, the key is unnamed.", "type": [ "string", "null" ] }, "name": { "description": "Human-readable organization name.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "SetupOrganizationResponse": { "description": "Response body for `POST /v1/management/organizations/setup`.", "properties": { "key": { "$ref": "#/components/schemas/OrganizationEventAccessView", "description": "The freshly minted service-account key scoped to the new\norganization. The `accessKey` field is the only point at which the\nfull secret is exposed." }, "organization": { "$ref": "#/components/schemas/OrganizationView", "description": "The newly created organization." } }, "required": [ "organization", "key" ], "type": "object" }, "Spec": { "properties": { "category": { "type": "string" }, "description": { "type": "string" }, "helperLink": { "type": [ "string", "null" ] }, "image": { "type": "string" }, "markdown": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" } }, "required": [ "title", "description", "platform", "category", "image", "tags" ], "type": "object" }, "SpecifyParams": { "properties": { "methods": { "items": { "$ref": "#/components/schemas/Method" }, "type": [ "array", "null" ] }, "rules": { "items": { "$ref": "#/components/schemas/AccessRule" }, "type": [ "array", "null" ] } }, "type": "object" }, "StartAiAgentSeatTrialParams": { "description": "A trial is always a single seat, so this carries only where Stripe should\nsend the caller back.", "properties": { "cancelUrl": { "type": "string" }, "successUrl": { "type": "string" } }, "required": [ "successUrl", "cancelUrl" ], "type": "object" }, "TemplateBody": { "properties": { "connectorRules": { "items": { "$ref": "#/components/schemas/ConnectorRule" }, "type": "array" }, "customerFacingName": { "$ref": "#/components/schemas/NonEmptyString" }, "darkLogoUrl": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "lightLogoUrl": { "type": [ "string", "null" ] }, "name": { "$ref": "#/components/schemas/NonEmptyString" }, "successMessage": { "$ref": "#/components/schemas/NonEmptyString" }, "welcomeMessage": { "$ref": "#/components/schemas/NonEmptyString" } }, "required": [ "name", "customerFacingName", "welcomeMessage", "successMessage", "connectorRules" ], "type": "object" }, "TokenResponse": { "allOf": [ { "$ref": "#/components/schemas/Paginated_ConnectedPlatformView" }, { "properties": { "isWhiteLabel": { "type": "boolean" }, "requestId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OAuthRequestId" } ] } }, "required": [ "isWhiteLabel" ], "type": "object" } ] }, "UpdateAiAgentParams": { "properties": { "active": { "type": [ "boolean", "null" ] }, "channels": {}, "description": { "type": [ "string", "null" ] }, "guardrails": {}, "memory": {}, "model": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiAgentModelType" } ] }, "modelId": { "type": [ "string", "null" ] }, "modelProvider": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiModelProviderType" } ] }, "name": { "type": [ "string", "null" ] }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiAgentStatusType" } ] }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "tools": {}, "triggers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiAgentTriggers" } ] } }, "type": "object" }, "UpdateAiSkillParams": { "properties": { "active": { "type": [ "boolean", "null" ] }, "agent": { "type": [ "string", "null" ] }, "allowedTools": {}, "argumentHint": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "context": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "disableModelInvocation": { "type": [ "boolean", "null" ] }, "hooks": {}, "model": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "public": { "type": [ "boolean", "null" ] }, "skipValidation": { "type": [ "boolean", "null" ] }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "userInvocable": { "type": [ "boolean", "null" ] } }, "type": "object" }, "UpdateConnection": { "properties": { "name": { "description": "New display name for the connection. Empty string clears it;\nwhen omitted, the name is left untouched.", "type": [ "string", "null" ] }, "tags": { "description": "New tag set for the connection, checked by the shared tag check in\nthe handler. When omitted, tags are left untouched.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "UpdateEndpointParams": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/CreateRelayAction" }, "type": [ "array", "null" ] }, "active": { "type": [ "boolean", "null" ] }, "description": { "type": [ "string", "null" ] }, "eventFilters": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "UpdateMemberRoleParams": { "additionalProperties": false, "description": "Body for member role-update endpoints (org and project).", "properties": { "roleKey": { "$ref": "#/components/schemas/RoleHierarchy", "description": "Target role. Wire format matches the enum variant exactly\n(`Member`, `Manager`, `Admin`)." }, "userId": { "format": "uuid", "type": "string" } }, "required": [ "userId", "roleKey" ], "type": "object" }, "UpdateOrganizationSettingsParams": { "additionalProperties": false, "description": "Body for `PUT /v1/management/organizations/{org_id}`.\n\nBoth fields are optional individually; omitted fields are left\nunchanged. The schema-level `example` is here so the generated docs\nrender a usable curl body instead of `{}`.", "example": { "description": "Updated tenant description", "name": "Acme Corp" }, "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" }, "UpdateParams": { "properties": { "accessTokenTtl": { "description": "Access-token lifetime in seconds, one of the offered choices; any other value is refused. Omit to leave the current lifetime unchanged - there is no way to clear it back to the platform default once set.", "enum": [ 604800, 2592000, 7776000, 31536000, null ], "format": "int32", "type": [ "integer", "null" ] }, "consentSurface": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConsentSurface", "description": "Where this client's users grant consent. Omitting it leaves the current\nsurface alone, like every other field here." } ] }, "description": { "type": [ "string", "null" ] }, "homepageUrl": { "type": [ "string", "null" ] }, "isActive": { "type": [ "boolean", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "name": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NonEmptyString" } ] }, "redirectUris": { "items": { "$ref": "#/components/schemas/NonEmptyString" }, "type": [ "array", "null" ] } }, "type": "object" }, "UpdateProjectParams": { "additionalProperties": false, "description": "Body for `PUT\n/v1/management/organizations/{org_id}/projects/{project_id}`.\n\nBoth fields are optional individually; omitted fields are left\nunchanged. Schema-level `example` for the same docs reason as\n[`UpdateOrganizationSettingsParams`].", "example": { "description": "Updated project description", "name": "Production" }, "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" }, "UpdateSubscriptionParams": { "properties": { "active": { "type": [ "boolean", "null" ] }, "description": { "type": [ "string", "null" ] }, "events": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": [ "array", "null" ] }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "secret": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" }, "UpsertOrganizationAuthKitParams": { "additionalProperties": false, "description": "Request body for `PUT\n/v1/management/organizations/{org_id}/authkit`.", "properties": { "active": { "description": "Whether this OAuth configuration is enabled. When `false` the\nplatform is hidden from the Embeddable Auth picker for end\nusers in this scope and environment, even if credentials are\npresent.", "type": "boolean" }, "clientId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NonEmptyString", "description": "OAuth 2.0 client ID issued by the platform's developer console\nfor your OAuth app. Required when `useDefaultOauthCreds` is\nfalse or omitted. Ignored when `useDefaultOauthCreds` is true." } ] }, "clientSecret": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NonEmptyString", "description": "OAuth 2.0 client secret paired with `clientId`. Stored\nencrypted at rest and never returned in responses. Required\nwhen `useDefaultOauthCreds` is false or omitted. Ignored when\n`useDefaultOauthCreds` is true." } ] }, "connectionDefinitionId": { "$ref": "#/components/schemas/ConnectionDefinitionId" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment", "description": "Which environment (`test` or `live`) this configuration\napplies to. Each environment has its own row, so a test OAuth\napp and a live OAuth app can coexist for the same platform." }, "guide": { "description": "Optional URL shown behind the \"View connection guide\" link in\nthe Embeddable Auth component for this platform. Typically a\npage in your docs explaining how end users should obtain\nwhatever the platform requires (account, workspace, etc.)\nbefore connecting. Must be an absolute `http://` or `https://`\nURL; other schemes (`javascript:`, `data:`, `file:`, \u2026) are\nrejected to prevent stored-XSS / phishing on dashboards and\nthe AuthKit widget that render this value as a clickable link.", "type": [ "string", "null" ] }, "scopes": { "description": "Space-separated list of OAuth scopes to request from the\nplatform (RFC 6749 \u00a73.3 format, e.g.\n`\"read:user offline_access\"`). Applied to both the\nauthorization-URL `scope` parameter and the client-credentials\ntoken exchange. Leave unset to use the platform's default\nscope set.", "type": [ "string", "null" ] }, "useDefaultOauthCreds": { "description": "When `true`, use Pica's managed OAuth app for this platform\ninstead of supplying your own `clientId` and `clientSecret`.", "type": [ "boolean", "null" ] } }, "required": [ "connectionDefinitionId", "environment", "active" ], "type": "object" }, "UpsertSubscriptionParams": { "description": "Body of the idempotent upsert. `secret` is required, unlike on create: the\ndelivery path only signs when a subscription has one, so a secretless\nlistener would receive bodies a client cannot verify.", "properties": { "active": { "type": [ "boolean", "null" ] }, "description": { "type": [ "string", "null" ] }, "events": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "secret": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "events", "secret" ], "type": "object" }, "UserFlags": { "properties": { "accessList": { "items": { "type": "string" }, "type": "array" }, "authkitWhitelist": { "type": "boolean" }, "completedQuickstart": { "type": "boolean" }, "earlyAccess": { "items": { "$ref": "#/components/schemas/Value" }, "type": "array" } }, "type": "object" }, "Value": {}, "VaultConnectionView": { "properties": { "active": { "type": "boolean" }, "connector": { "description": "The connector behind this connection. Carried because a grant bounded\nby connectors decides on it, so a caller rendering what a token may do\nhere would otherwise have to resolve it by a second lookup per row.", "type": "string" }, "description": { "type": "string" }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "id": { "format": "uuid", "type": "string" }, "identity": { "type": [ "string", "null" ] }, "identityType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionIdentityType" } ] }, "image": { "type": "string" }, "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "platformVersion": { "type": "string" }, "state": { "$ref": "#/components/schemas/ConnectionStateType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/ConnectionType" }, "version": { "type": "string" } }, "required": [ "id", "connector", "platformVersion", "type", "key", "environment", "platform", "description", "image", "version", "state", "tags", "active" ], "type": "object" }, "VerificationStatus": { "enum": [ "pending", "verified", "rejected" ], "type": "string" }, "WebhookEventType": { "description": "Auto-generated discriminant enum variants", "enum": [ "connection.created", "connection.oauth.created", "connection.updated", "connection.deleted", "api_key.created", "api_key.revoked", "project.created", "project.updated", "project.deleted", "organization.created", "organization.updated", "organization.deleted", "oauth.refreshed", "oauth.failed", "passthrough.executed", "member.added", "member.removed", "member.role_updated" ], "type": "string" }, "WebhookEventView": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "eventType": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "metadata": { "$ref": "#/components/schemas/Value" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "payload": { "$ref": "#/components/schemas/Value" }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "timestamp": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "eventType", "payload", "timestamp", "metadata", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "WebhookFrontend": { "properties": { "formData": { "items": { "$ref": "#/components/schemas/FormDataItem" }, "type": "array" } }, "required": [ "formData" ], "type": "object" }, "WebhookPayload": { "description": "Every webhook event and the payload its deliveries carry.\n\nThe single declaration of the catalog: [`WebhookEventType`] is derived from\nit, so an event cannot exist without a payload and the two cannot drift.\n\nNever serialized: a delivery puts the bare payload under `payload` with the\ndiscriminant in the sibling `event` field. The serde tag exists so utoipa\nderives a `oneOf` with a `discriminator` whose `mapping` pairs every event\nwith its payload schema - that mapping is what the SDK generators read, and\nit comes from this declaration rather than being restated anywhere.", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ConnectionCreatedPayload", "description": "Emitted when a new non-OAuth connection is created" }, { "properties": { "type": { "enum": [ "connection.created" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a new non-OAuth connection is created" }, { "allOf": [ { "$ref": "#/components/schemas/ConnectionOAuthCreatedPayload", "description": "Emitted when an OAuth connection is created" }, { "properties": { "type": { "enum": [ "connection.oauth.created" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when an OAuth connection is created" }, { "allOf": [ { "$ref": "#/components/schemas/ConnectionUpdatedPayload", "description": "Emitted when a connection's own fields change" }, { "properties": { "type": { "enum": [ "connection.updated" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a connection's own fields change" }, { "allOf": [ { "$ref": "#/components/schemas/ConnectionDeletedPayload", "description": "Emitted when a connection is deleted" }, { "properties": { "type": { "enum": [ "connection.deleted" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a connection is deleted" }, { "allOf": [ { "$ref": "#/components/schemas/ApiKeyCreatedPayload", "description": "Emitted when an API key is created" }, { "properties": { "type": { "enum": [ "api_key.created" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when an API key is created" }, { "allOf": [ { "$ref": "#/components/schemas/ApiKeyRevokedPayload", "description": "Emitted when an API key is revoked" }, { "properties": { "type": { "enum": [ "api_key.revoked" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when an API key is revoked" }, { "allOf": [ { "$ref": "#/components/schemas/ProjectCreatedPayload", "description": "Emitted when a project is created" }, { "properties": { "type": { "enum": [ "project.created" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a project is created" }, { "allOf": [ { "$ref": "#/components/schemas/ProjectUpdatedPayload", "description": "Emitted when a project is updated" }, { "properties": { "type": { "enum": [ "project.updated" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a project is updated" }, { "allOf": [ { "$ref": "#/components/schemas/ProjectDeletedPayload", "description": "Emitted when a project is deleted" }, { "properties": { "type": { "enum": [ "project.deleted" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a project is deleted" }, { "allOf": [ { "$ref": "#/components/schemas/OrganizationCreatedPayload", "description": "Emitted when an organization is created" }, { "properties": { "type": { "enum": [ "organization.created" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when an organization is created" }, { "allOf": [ { "$ref": "#/components/schemas/OrganizationUpdatedPayload", "description": "Emitted when an organization is updated" }, { "properties": { "type": { "enum": [ "organization.updated" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when an organization is updated" }, { "allOf": [ { "$ref": "#/components/schemas/OrganizationDeletedPayload", "description": "Emitted when an organization is deleted" }, { "properties": { "type": { "enum": [ "organization.deleted" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when an organization is deleted" }, { "allOf": [ { "$ref": "#/components/schemas/OAuthRefreshedPayload", "description": "Emitted when OAuth token is refreshed" }, { "properties": { "type": { "enum": [ "oauth.refreshed" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when OAuth token is refreshed" }, { "allOf": [ { "$ref": "#/components/schemas/OAuthFailedPayload", "description": "Emitted when OAuth authorization fails" }, { "properties": { "type": { "enum": [ "oauth.failed" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when OAuth authorization fails" }, { "allOf": [ { "$ref": "#/components/schemas/PassthroughExecutedPayload", "description": "Emitted when a passthrough request is executed" }, { "properties": { "type": { "enum": [ "passthrough.executed" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a passthrough request is executed" }, { "allOf": [ { "$ref": "#/components/schemas/MemberAddedPayload", "description": "Emitted when a member is added to an organization or project" }, { "properties": { "type": { "enum": [ "member.added" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a member is added to an organization or project" }, { "allOf": [ { "$ref": "#/components/schemas/MemberRemovedPayload", "description": "Emitted when a member is removed from an organization or project" }, { "properties": { "type": { "enum": [ "member.removed" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a member is removed from an organization or project" }, { "allOf": [ { "$ref": "#/components/schemas/MemberRoleUpdatedPayload", "description": "Emitted when a member's role is updated" }, { "properties": { "type": { "enum": [ "member.role_updated" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ], "description": "Emitted when a member's role is updated" } ] }, "WebhookRelayEndpointView": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/RelayActionView" }, "type": "array" }, "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionId": { "format": "uuid", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "eventFilters": { "items": { "type": "string" }, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "url": { "type": [ "string", "null" ] }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" }, "warning": { "type": [ "string", "null" ] }, "webhookPayload": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] } }, "required": [ "id", "connectionId", "userId", "actions", "eventFilters", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "WebhookRelayEventView": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "connectionId": { "format": "uuid", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "eventType": { "type": [ "string", "null" ] }, "headers": { "$ref": "#/components/schemas/Value" }, "id": { "format": "uuid", "type": "string" }, "metadata": { "$ref": "#/components/schemas/Value" }, "payload": { "$ref": "#/components/schemas/Value" }, "platform": { "type": "string" }, "signatureValid": { "type": [ "boolean", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "timestamp": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "connectionId", "userId", "platform", "headers", "payload", "timestamp", "metadata", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "WebhookRelayPlatformInfo": { "properties": { "eventTypeCount": { "minimum": 0, "type": "integer" }, "platform": { "type": "string" } }, "required": [ "platform", "eventTypeCount" ], "type": "object" }, "WebhookSubscriptionView": { "properties": { "active": { "type": "boolean" }, "changeLog": { "$ref": "#/components/schemas/ChangeLog" }, "createdAt": { "format": "date-time", "type": "string" }, "deleted": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "events": { "items": { "type": "string" }, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "key": { "type": "string" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Value" } ] }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "url": { "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "userId", "url", "key", "events", "createdAt", "updatedAt", "version", "deleted", "changeLog", "tags", "active" ], "type": "object" }, "WhoamiOrganization": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "WhoamiProject": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "WhoamiResponse": { "properties": { "organization": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WhoamiOrganization" } ] }, "project": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WhoamiProject" } ] }, "user": { "$ref": "#/components/schemas/WhoamiUser" } }, "required": [ "user" ], "type": "object" }, "WhoamiUser": { "properties": { "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name", "email" ], "type": "object" }, "YankBody": { "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "type": "object" } }, "securitySchemes": { "Bearer": { "scheme": "bearer", "type": "http" }, "OAuth2": { "flows": { "authorizationCode": { "authorizationUrl": "https://api.withone.ai/oauth/authorize", "scopes": { "org:ai_skills:read": "Read organization AI skills", "org:ai_skills:write": "Create, update, and delete organization AI skills", "org:authkit:read": "Read organization AuthKit resources", "org:authkit:write": "Create, update, and delete organization AuthKit resources", "org:connections:read": "Read organization connections", "org:connections:write": "Create, update, and delete organization connections", "org:projects:read": "Read organization projects", "org:projects:write": "Create, update, and delete organization projects", "org:secrets:read": "Read organization secrets", "org:secrets:write": "Create, update, and delete organization secrets", "org:workflows:executions:read": "Read organization workflow executions", "org:workflows:executions:write": "Create, update, and delete organization workflow executions", "org:workflows:read": "Read organization workflows", "org:workflows:write": "Create, update, and delete organization workflows", "project:ai_skills:read": "Read project AI skills", "project:ai_skills:write": "Create, update, and delete project AI skills", "project:authkit:read": "Read project AuthKit resources", "project:authkit:write": "Create, update, and delete project AuthKit resources", "project:connections:read": "Read project connections", "project:connections:write": "Create, update, and delete project connections", "project:secrets:read": "Read project secrets", "project:secrets:write": "Create, update, and delete project secrets", "project:workflows:executions:read": "Read project workflow executions", "project:workflows:executions:write": "Create, update, and delete project workflow executions", "project:workflows:read": "Read project workflows", "project:workflows:write": "Create, update, and delete project workflows", "user:ai_skills:read": "Read your personal AI skills", "user:ai_skills:write": "Create, update, and delete your personal AI skills", "user:authkit:read": "Read your personal AuthKit resources", "user:authkit:write": "Create, update, and delete your personal AuthKit resources", "user:connections:read": "Read your personal connections", "user:connections:write": "Create, update, and delete your personal connections", "user:secrets:read": "Read your personal secrets", "user:secrets:write": "Create, update, and delete your personal secrets", "user:workflows:executions:read": "Read your personal workflow executions", "user:workflows:executions:write": "Create, update, and delete your personal workflow executions", "user:workflows:read": "Read your personal workflows", "user:workflows:write": "Create, update, and delete your personal workflows" }, "tokenUrl": "https://api.withone.ai/oauth/token" } }, "type": "oauth2" }, "Session": { "in": "cookie", "name": "withone", "type": "apiKey" }, "X-One-Connection-Key": { "in": "header", "name": "X-One-Connection-Key", "type": "apiKey" }, "X-One-Secret": { "in": "header", "name": "X-One-Secret", "type": "apiKey" }, "X-Pica-Connection-Key": { "in": "header", "name": "X-One-Connection-Key", "type": "apiKey" }, "X-Pica-Secret": { "in": "header", "name": "X-One-Secret", "type": "apiKey" } } }, "info": { "description": "The One API. Universal API integration platform for AI agents and applications.", "license": { "name": "" }, "title": "One API", "version": "5.35.0" }, "openapi": "3.1.0", "paths": { "/oauth/authorize/actions": { "get": { "description": "The ceremony's own catalog leg rather than the open `/open/knowledge`\nroutes, because the ceremony's offer bounds which platform may be asked\nabout at all, which the open routes do not.", "operationId": "oauth_authorize_actions", "parameters": [ { "in": "query", "name": "state_key", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "platform", "required": true, "schema": { "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_OpenKnowledgeActionListItem" } } }, "description": "The platform's actions, as the picker lists them" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid consent submission" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded - upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authorization request not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many ceremonies opened for this client" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "summary": "A platform's actions from the open catalog, for the card's custom picker.", "tags": [ "OAuth" ] } }, "/oauth/authorize/actions/search": { "get": { "operationId": "oauth_authorize_actions_search", "parameters": [ { "in": "query", "name": "state_key", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "platform", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": true, "schema": { "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/OpenKnowledgeActionListItem" }, "type": "array" } } }, "description": "The platform's actions most relevant to the search text" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid consent submission" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded - upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authorization request not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many ceremonies opened for this client" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "summary": "[`authorize_actions`], answered by relevance to the picker's search text.", "tags": [ "OAuth" ] } }, "/oauth/authorize/activate": { "post": { "description": "The card shows a net-new end user the connectors the app offers, not only\nthe ones already stood up for them; a connector on offer with no active\n`connected_platform` is *prospective*, and the completion gate refuses it\nuntil a row exists. This leg writes that row on the user's deliberate pick -\nnever on render - and returns the platform the card then runs the ordinary\nconnect against, the same [`ConnectedPlatformView`] shape the connect\nlisting returns so the widget consumes it identically.\n\nA `POST` and, unlike the card's reads, a **write**: it stands up a shared\n`connected_platform` and copies One's default credential to the user, so it\ntakes the same `first_party_origin: client` guard and AuthKit **create**\nauthority as [`authorize_connect`], not the reads' laxer stance.\n\nThe tenant headers are declared by hand for the reason\n[`authorize_connections`] gives.", "operationId": "oauth_authorize_activate", "parameters": [ { "in": "query", "name": "state_key", "required": true, "schema": { "type": "string" } }, { "description": "Selects the organization this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": [ "string", "null" ] } }, { "description": "Selects the project this request acts in, inside the organization above.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedPlatformView" } } }, "description": "The freshly stood-up platform, ready for the connect" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid consent submission" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded - upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authorization request not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many ceremonies opened for this client" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "summary": "Stands up an offered-but-prospective connector so the card can connect it.", "tags": [ "OAuth" ] } }, "/oauth/authorize/connect": { "post": { "description": "The other half of [`authorize_connections`]: that answers \"what do you\nalready have\", this answers \"what can you add\". Both narrow to the same\noffer, so a connector the ceremony never asked for is neither reported as\nheld nor offered as connectable.\n\nA `POST` because it mints that request; the listing rides along because the\ncard renders both together and a second round trip would let the two\ndisagree about which connectors are on offer.\n\nThe tenant headers are declared by hand for the reason\n[`authorize_connections`] gives.", "operationId": "oauth_authorize_connect", "parameters": [ { "in": "query", "name": "state_key", "required": true, "schema": { "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the organization this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": [ "string", "null" ] } }, { "description": "Selects the project this request acts in, inside the organization above.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareInitParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CeremonyConnectResponse" } } }, "description": "The platforms on offer, and the request to carry into one" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid consent submission" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded - upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authorization request not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many ceremonies opened for this client" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "summary": "The platforms the card may offer, and the OAuth request the one the user\npicks will be recorded against.", "tags": [ "OAuth" ] } }, "/oauth/authorize/connections": { "get": { "description": "Lets the card show which of the ceremony's connectors are already done, so a\nuser is not asked to reconnect something they have. Unlike\n[`authorize_context`] this needs a caller: there is no useful anonymous\nanswer, and the tenancy it reads is the viewer's own.\n\n**The tenant headers are declared here by hand**, unlike the tiered routes\nwhere the spec builder injects them. That injector derives selectors from a\nroute's `oauth_scopes`, and this route has none - it is reachable by\nsession, never by a bearer - so nothing would publish them and a generated\nclient would silently ask for personal scope.", "operationId": "oauth_authorize_connections", "parameters": [ { "in": "query", "name": "state_key", "required": true, "schema": { "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the organization this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": [ "string", "null" ] } }, { "description": "Selects the project this request acts in, inside the organization above.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_CeremonyConnectionView" } } }, "description": "The caller's connections in the named tenant" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid consent submission" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded - upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authorization request not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many ceremonies opened for this client" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "summary": "The connections the signed-in user already holds in the tenant they picked.", "tags": [ "OAuth" ] } }, "/oauth/authorize/context": { "get": { "description": "**Deliberately readable without a session.** The card is framed by the\ncustomer's app, and it has to be able to ask \"who is signed in?\" before it\nknows the answer - `viewer: null` is what tells it to show sign-in. Reading\nthe session when there *is* one is equally deliberate: a user already signed\nin to the dashboard must not be shown sign-in again, because signing in\nafresh cycles their session id and revokes the event-access keys attached to\nthe old one. Using a partner's card would quietly sign them out.\n\nThe state key is the capability. It is HMAC-signed at authorize time and\nverified here before anything is looked up, so it cannot be guessed; an\nunsigned or tampered key is indistinguishable from an unknown one (404).", "operationId": "oauth_authorize_context", "parameters": [ { "in": "query", "name": "state_key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentContext" } } }, "description": "The ceremony as the caller may see it" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid consent submission" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded - upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authorization request not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many ceremonies opened for this client" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ {}, { "Session": [] } ], "summary": "What the connect card needs to render one in-flight consent ceremony.", "tags": [ "OAuth" ] } }, "/oauth/authorize/prior-grant": { "get": { "description": "Lets a reconnect card pre-select the exact account and level the user\nalready granted rather than the app's requested set, so re-authorizing\ncannot silently widen a grant they had narrowed. A single durable-grant read\nkeyed on the caller and the ceremony's client, filtered to the tenant the\ncard is opened in: the request carries the same `X-One-Organization-Id` /\n`X-One-Project-Id` selectors as the connections read, so a grant made in one\ntenant is never pre-selected in another. The domain proves ceremony\nownership.", "operationId": "oauth_authorize_prior_grant", "parameters": [ { "in": "query", "name": "state_key", "required": true, "schema": { "type": "string" } }, { "description": "Selects the organization the card is opened in, so the grant is filtered to it. Omit it to read a personal-scope grant; a grant made under an organization is not returned in personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": [ "string", "null" ] } }, { "description": "Selects the project the card is opened in, inside the organization above. A project-limited grant is returned only at its own project scope, never at the parent organization.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "description": "What a grant reaches, generic over how each entry is rendered - the one\ntrichotomy two surfaces share: a dashboard reads it as counts\n([`GrantedReachView`]), a reconnect card as pre-selectable rules\n([`PriorGrantView`]). `KnowledgeOnly`/`Full` are identical on the wire for\nboth; only the `Connectors` element type differs.\n\nA bare generic derives a single schema named `ReachView`, so both\ninstantiations would collide on that one OpenAPI component and one endpoint\nwould advertise the other's connector shape. Every schema site that carries\none of these therefore inlines it (`#[schema(inline)]` / `inline(...)`), so\nno shared `ReachView` component exists to collide.", "oneOf": [ { "description": "Docs and search only: no connection access of any kind.", "properties": { "type": { "enum": [ "knowledgeOnly" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Every connection in the consented scope. No connector list because the\ngrant names none - it follows the account.", "properties": { "type": { "enum": [ "full" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "description": "Only what the grant names, each entry rendered as `C`. **The granularity\nis the instantiation's**: a reach report carries one entry per\nconnector, a prior grant one per granted *connection*, so two entries\nthere can share a connector.", "properties": { "connectors": { "items": { "$ref": "#/components/schemas/PriorGrantConnectorView" }, "type": "array" }, "type": { "enum": [ "connectors" ], "type": "string" } }, "required": [ "connectors", "type" ], "type": "object" } ] } ] } } }, "description": "The caller's grant for the client in the selected tenant, or null when they have not authorized it there" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid consent submission" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded - upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authorization request not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many ceremonies opened for this client" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "summary": "The user's existing grant for the ceremony's client, one entry per granted\nconnection.", "tags": [ "OAuth" ] } }, "/v1/access/organizations/{org_id}/projects/{project_id}/{id}": { "delete": { "description": "Requires the `access:delete` permission within the project.", "operationId": "revoke_project_connection_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "responses": { "200": { "description": "All access restrictions removed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Remove all connection access restrictions from a project-level access key.", "tags": [ "Access" ] }, "get": { "operationId": "read_project_connection_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccessResponse" } ] } } }, "description": "Current access restrictions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "Access" ] }, "put": { "description": "Requires the `access:update` permission within the project.", "operationId": "update_project_connection_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecifyParams" } } }, "required": true }, "responses": { "200": { "description": "Access restrictions updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Update connection access restrictions for a project-level access key.", "tags": [ "Access" ] } }, "/v1/access/organizations/{org_id}/{id}": { "delete": { "description": "Requires the `access:delete` permission within the organization.", "operationId": "revoke_organization_connection_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "responses": { "200": { "description": "All access restrictions removed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Remove all connection access restrictions from an organization-level access\nkey.", "tags": [ "Access" ] }, "get": { "operationId": "read_organization_connection_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccessResponse" } ] } } }, "description": "Current access restrictions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "Access" ] }, "put": { "description": "Requires the `access:update` permission within the organization.", "operationId": "update_organization_connection_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecifyParams" } } }, "required": true }, "responses": { "200": { "description": "Access restrictions updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Update connection access restrictions for an organization-level access key.", "tags": [ "Access" ] } }, "/v1/access/{id}": { "delete": { "description": "After revoking, the key will have unrestricted access to all connections,\nplatforms, and methods.", "operationId": "revoke_connection_access", "parameters": [ { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "responses": { "200": { "description": "All access restrictions removed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Remove all connection access restrictions from a user-level access key.", "tags": [ "Access" ] }, "get": { "description": "Returns the active restrictions (methods, rules) or null\nif no restrictions have been applied.", "operationId": "read_connection_access", "parameters": [ { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccessResponse" } ] } } }, "description": "Current access restrictions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Retrieve current connection access restrictions for a user-level access key.", "tags": [ "Access" ] }, "post": { "description": "The scope is determined automatically from the target event access key's\norganization and project context. Permission checks are applied accordingly:\n- **User-level keys:** caller must own the key.\n- **Organization-level keys:** caller must have `access:update` permission\n in the organization.\n- **Project-level keys:** caller must have `access:update` permission in the\n project.\n\nGlobal `methods` apply to all connections unless overridden by a rule.\nEach rule targets a specific platform or connection and can override\nthe global methods. When rules are present, only matching\nconnections/platforms are allowed.\n\nConnection IDs in rules are validated to exist within the same scope\nas the access key.", "operationId": "specify_connection_access", "parameters": [ { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecifyParams" } } }, "required": true }, "responses": { "200": { "description": "Access restrictions applied" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Specify connection access restrictions for an access key (auto-scoped).", "tags": [ "Access" ] }, "put": { "description": "Replaces the existing access control rules. At least one of methods or\nrules must be provided.", "operationId": "update_connection_access", "parameters": [ { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/EventAccessId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecifyParams" } } }, "required": true }, "responses": { "200": { "description": "Access restrictions updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Update connection access restrictions for a user-level access key.", "tags": [ "Access" ] } }, "/v1/ai-agents": { "get": { "description": "Returns the AI agents in your account. Test and live environments are isolated \u2014 you'll only see agents that match the environment of your API key.", "operationId": "list_ai_agents", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "channels": {}, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "guardrails": {}, "id": { "format": "uuid", "type": "string" }, "memory": {}, "model": { "$ref": "#/components/schemas/AiAgentModelType" }, "modelId": { "type": [ "string", "null" ] }, "modelProvider": { "$ref": "#/components/schemas/AiModelProviderType" }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "runnerStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PodStatusType", "description": "The state of this agent's runner, when it has one.\n\nThe agent's own lifecycle and its pod's are separate, and this field is\nwhat lets a caller see the second without conflating it into the first.\nAn agent that has never been run has no pod and reports `None`; one\nwhose pod was stopped - by the owner, or by a lapsed seat culling it -\nreports [`PodStatusType::Terminated`], which is what a console renders\nas paused.\n\nPopulated only by the read paths that opt in through\n[`ViewWithCtxExt::into_view_with_ctx`], so the write paths pay nothing\nfor it.\nAbsent from the wire rather than null when there is no runner, so a\nresponse for an agent that has never run is byte-identical to before." } ] }, "runnerStopReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PodStopReasonType", "description": "What stopped the runner, when it is stopped.\n\n`runnerStatus` alone cannot say: a pause the owner performed and a stop\nbilling performed both read `terminated`, which is the whole reason this\nexists. Absent while the runner is live, and on pods stopped before it\nwas recorded.\n\n**A cause, not a prediction.** It records the stop that happened and\nnothing re-derives it afterwards, so entitlement can move underneath it\nin both directions: an owner-paused agent stays `user_requested` when\nits seat later lapses, because the cull only counts what is running,\nyet `ensure` counts every undeleted agent and will refuse it; and a\nculled agent stays `seat_lapsed` after a replacement seat is bought,\nuntil a resume clears it. Use it to explain what happened - and ask\n`ensure` whether the agent can start, rather than guessing from\nthis." } ] }, "runtime": { "$ref": "#/components/schemas/AiRuntimeType" }, "status": { "$ref": "#/components/schemas/AiAgentStatusType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "tools": {}, "trialSeat": { "description": "Whether this agent occupies the owner's free-trial seat.\n\nWorth surfacing because it decides what happens when the trial ends:\nthis is the agent stopped first, ahead of the least recently used. It\nis also the only way a caller learns whether a `useTrial` create took\neffect, since that flag is ignored rather than rejected when there is\nno live trial or another agent already holds the seat.\n\nAbsent from the wire rather than `false` on the paths that do not\nresolve it, so \"not on the trial seat\" is never confused with \"not\nasked\".", "type": [ "boolean", "null" ] }, "triggers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiAgentTriggers" } ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" }, "volumeId": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "id", "userId", "name", "model", "status", "tools", "environment", "runtime", "modelProvider", "createdAt", "updatedAt", "version", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" } } }, "description": "List of AI agents" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List AI agents", "tags": [ "AI Agents" ] }, "post": { "description": "Creates a new AI agent. Choose the model, the skills it can call, any guardrails, channels it should respond on, triggers that wake it up, and an optional memory store. Subject to your plan's AI-agent quota.", "operationId": "create_ai_agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiAgentParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentView" } } }, "description": "Created AI agent" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create AI agent", "tags": [ "AI Agents" ] } }, "/v1/ai-agents/organizations/{org_id}": { "get": { "description": "Returns the AI agents owned by an organization. Filtered automatically to the environment (test or live) of your API key.", "operationId": "list_org_ai_agents", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "channels": {}, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "guardrails": {}, "id": { "format": "uuid", "type": "string" }, "memory": {}, "model": { "$ref": "#/components/schemas/AiAgentModelType" }, "modelId": { "type": [ "string", "null" ] }, "modelProvider": { "$ref": "#/components/schemas/AiModelProviderType" }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "runnerStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PodStatusType", "description": "The state of this agent's runner, when it has one.\n\nThe agent's own lifecycle and its pod's are separate, and this field is\nwhat lets a caller see the second without conflating it into the first.\nAn agent that has never been run has no pod and reports `None`; one\nwhose pod was stopped - by the owner, or by a lapsed seat culling it -\nreports [`PodStatusType::Terminated`], which is what a console renders\nas paused.\n\nPopulated only by the read paths that opt in through\n[`ViewWithCtxExt::into_view_with_ctx`], so the write paths pay nothing\nfor it.\nAbsent from the wire rather than null when there is no runner, so a\nresponse for an agent that has never run is byte-identical to before." } ] }, "runnerStopReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PodStopReasonType", "description": "What stopped the runner, when it is stopped.\n\n`runnerStatus` alone cannot say: a pause the owner performed and a stop\nbilling performed both read `terminated`, which is the whole reason this\nexists. Absent while the runner is live, and on pods stopped before it\nwas recorded.\n\n**A cause, not a prediction.** It records the stop that happened and\nnothing re-derives it afterwards, so entitlement can move underneath it\nin both directions: an owner-paused agent stays `user_requested` when\nits seat later lapses, because the cull only counts what is running,\nyet `ensure` counts every undeleted agent and will refuse it; and a\nculled agent stays `seat_lapsed` after a replacement seat is bought,\nuntil a resume clears it. Use it to explain what happened - and ask\n`ensure` whether the agent can start, rather than guessing from\nthis." } ] }, "runtime": { "$ref": "#/components/schemas/AiRuntimeType" }, "status": { "$ref": "#/components/schemas/AiAgentStatusType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "tools": {}, "trialSeat": { "description": "Whether this agent occupies the owner's free-trial seat.\n\nWorth surfacing because it decides what happens when the trial ends:\nthis is the agent stopped first, ahead of the least recently used. It\nis also the only way a caller learns whether a `useTrial` create took\neffect, since that flag is ignored rather than rejected when there is\nno live trial or another agent already holds the seat.\n\nAbsent from the wire rather than `false` on the paths that do not\nresolve it, so \"not on the trial seat\" is never confused with \"not\nasked\".", "type": [ "boolean", "null" ] }, "triggers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiAgentTriggers" } ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" }, "volumeId": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "id", "userId", "name", "model", "status", "tools", "environment", "runtime", "modelProvider", "createdAt", "updatedAt", "version", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" } } }, "description": "List of organization AI agents" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List organization AI agents", "tags": [ "AI Agents" ] }, "post": { "description": "Creates a new AI agent owned by an organization. Org-scoped agents are visible across every project in the organization. Subject to the organization's plan quota.", "operationId": "create_org_ai_agent", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiAgentParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentView" } } }, "description": "Created organization AI agent" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create organization AI agent", "tags": [ "AI Agents" ] } }, "/v1/ai-agents/organizations/{org_id}/projects/{project_id}": { "get": { "description": "Returns the AI agents that live inside a project. Filtered automatically to the environment of your API key.", "operationId": "list_project_ai_agents", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "active": { "type": "boolean" }, "channels": {}, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "environment": { "$ref": "#/components/schemas/SecretKeyEnvironment" }, "guardrails": {}, "id": { "format": "uuid", "type": "string" }, "memory": {}, "model": { "$ref": "#/components/schemas/AiAgentModelType" }, "modelId": { "type": [ "string", "null" ] }, "modelProvider": { "$ref": "#/components/schemas/AiModelProviderType" }, "name": { "type": "string" }, "organizationId": { "format": "uuid", "type": [ "string", "null" ] }, "projectId": { "format": "uuid", "type": [ "string", "null" ] }, "runnerStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PodStatusType", "description": "The state of this agent's runner, when it has one.\n\nThe agent's own lifecycle and its pod's are separate, and this field is\nwhat lets a caller see the second without conflating it into the first.\nAn agent that has never been run has no pod and reports `None`; one\nwhose pod was stopped - by the owner, or by a lapsed seat culling it -\nreports [`PodStatusType::Terminated`], which is what a console renders\nas paused.\n\nPopulated only by the read paths that opt in through\n[`ViewWithCtxExt::into_view_with_ctx`], so the write paths pay nothing\nfor it.\nAbsent from the wire rather than null when there is no runner, so a\nresponse for an agent that has never run is byte-identical to before." } ] }, "runnerStopReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PodStopReasonType", "description": "What stopped the runner, when it is stopped.\n\n`runnerStatus` alone cannot say: a pause the owner performed and a stop\nbilling performed both read `terminated`, which is the whole reason this\nexists. Absent while the runner is live, and on pods stopped before it\nwas recorded.\n\n**A cause, not a prediction.** It records the stop that happened and\nnothing re-derives it afterwards, so entitlement can move underneath it\nin both directions: an owner-paused agent stays `user_requested` when\nits seat later lapses, because the cull only counts what is running,\nyet `ensure` counts every undeleted agent and will refuse it; and a\nculled agent stays `seat_lapsed` after a replacement seat is bought,\nuntil a resume clears it. Use it to explain what happened - and ask\n`ensure` whether the agent can start, rather than guessing from\nthis." } ] }, "runtime": { "$ref": "#/components/schemas/AiRuntimeType" }, "status": { "$ref": "#/components/schemas/AiAgentStatusType" }, "tags": { "items": { "type": "string" }, "type": "array" }, "tools": {}, "trialSeat": { "description": "Whether this agent occupies the owner's free-trial seat.\n\nWorth surfacing because it decides what happens when the trial ends:\nthis is the agent stopped first, ahead of the least recently used. It\nis also the only way a caller learns whether a `useTrial` create took\neffect, since that flag is ignored rather than rejected when there is\nno live trial or another agent already holds the seat.\n\nAbsent from the wire rather than `false` on the paths that do not\nresolve it, so \"not on the trial seat\" is never confused with \"not\nasked\".", "type": [ "boolean", "null" ] }, "triggers": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiAgentTriggers" } ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "format": "uuid", "type": "string" }, "version": { "type": "string" }, "volumeId": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "id", "userId", "name", "model", "status", "tools", "environment", "runtime", "modelProvider", "createdAt", "updatedAt", "version", "tags", "active" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" } } }, "description": "List of project AI agents" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List project AI agents", "tags": [ "AI Agents" ] }, "post": { "description": "Creates a new AI agent inside a project. Project-scoped agents are isolated to a single project. Subject to the project's plan quota.", "operationId": "create_project_ai_agent", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiAgentParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentView" } } }, "description": "Created project AI agent" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create project AI agent", "tags": [ "AI Agents" ] } }, "/v1/ai-agents/organizations/{org_id}/projects/{project_id}/{agent_id}/cron-runs": { "get": { "description": "Returns the recent scheduled invocations of a project-scoped AI agent.", "operationId": "list_project_ai_agent_cron_runs", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "agentId": { "format": "uuid", "type": "string" }, "completedAt": { "format": "date-time", "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "durationMs": { "format": "int32", "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "responsePreview": { "type": [ "string", "null" ] }, "scheduledAt": { "format": "date-time", "type": "string" }, "startedAt": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AiAgentCronRunStatusType" } }, "required": [ "id", "agentId", "scheduledAt", "status", "createdAt" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" } } }, "description": "List of project cron runs" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List project AI agent cron runs", "tags": [ "AI Agent Cron Runs" ] }, "post": { "description": "Records a single scheduled execution of a project-scoped AI agent.", "operationId": "create_project_ai_agent_cron_run", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpCreateCronRunParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentCronRunView" } } }, "description": "Created project cron run" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create project AI agent cron run", "tags": [ "AI Agent Cron Runs" ] } }, "/v1/ai-agents/organizations/{org_id}/projects/{project_id}/{agent_id}/cron-runs/{id}": { "get": { "description": "Returns a single scheduled-run record for a project-scoped AI agent.", "operationId": "get_project_ai_agent_cron_run", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Cron run ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentCronRunView" } } }, "description": "Project cron run details" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Get project AI agent cron run", "tags": [ "AI Agent Cron Runs" ] } }, "/v1/ai-agents/organizations/{org_id}/projects/{project_id}/{id}": { "delete": { "description": "Permanently removes a project-scoped AI agent and shuts down its running runner.", "operationId": "delete_project_ai_agent", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Deleted project AI agent" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Delete project AI agent", "tags": [ "AI Agents" ] }, "get": { "description": "Returns the full configuration of a project-scoped AI agent.", "operationId": "get_project_ai_agent", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentView" } } }, "description": "Project AI agent details" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Get project AI agent", "tags": [ "AI Agents" ] }, "patch": { "description": "Updates a project-scoped AI agent's configuration. Pass only the fields you want to change.", "operationId": "update_project_ai_agent", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAiAgentParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentView" } } }, "description": "Updated project AI agent" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Update project AI agent", "tags": [ "AI Agents" ] } }, "/v1/ai-agents/organizations/{org_id}/{agent_id}/cron-runs": { "get": { "description": "Returns the recent scheduled invocations of an organization-scoped AI agent.", "operationId": "list_org_ai_agent_cron_runs", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "agentId": { "format": "uuid", "type": "string" }, "completedAt": { "format": "date-time", "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "durationMs": { "format": "int32", "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "responsePreview": { "type": [ "string", "null" ] }, "scheduledAt": { "format": "date-time", "type": "string" }, "startedAt": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AiAgentCronRunStatusType" } }, "required": [ "id", "agentId", "scheduledAt", "status", "createdAt" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" } } }, "description": "List of organization cron runs" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List organization AI agent cron runs", "tags": [ "AI Agent Cron Runs" ] }, "post": { "description": "Records a single scheduled execution of an organization-scoped AI agent.", "operationId": "create_org_ai_agent_cron_run", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpCreateCronRunParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentCronRunView" } } }, "description": "Created organization cron run" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create organization AI agent cron run", "tags": [ "AI Agent Cron Runs" ] } }, "/v1/ai-agents/organizations/{org_id}/{agent_id}/cron-runs/{id}": { "get": { "description": "Returns a single scheduled-run record for an organization-scoped AI agent.", "operationId": "get_org_ai_agent_cron_run", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Cron run ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentCronRunView" } } }, "description": "Organization cron run details" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Get organization AI agent cron run", "tags": [ "AI Agent Cron Runs" ] } }, "/v1/ai-agents/organizations/{org_id}/{id}": { "delete": { "description": "Permanently removes an organization-scoped AI agent and shuts down its running runner.", "operationId": "delete_org_ai_agent", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Deleted organization AI agent" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Delete organization AI agent", "tags": [ "AI Agents" ] }, "get": { "description": "Returns the full configuration of an organization-scoped AI agent.", "operationId": "get_org_ai_agent", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentView" } } }, "description": "Organization AI agent details" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Get organization AI agent", "tags": [ "AI Agents" ] }, "patch": { "description": "Updates an organization-scoped AI agent's configuration. Pass only the fields you want to change.", "operationId": "update_org_ai_agent", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAiAgentParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentView" } } }, "description": "Updated organization AI agent" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Update organization AI agent", "tags": [ "AI Agents" ] } }, "/v1/ai-agents/{agent_id}/cron-runs": { "get": { "description": "Returns the recent scheduled invocations of an AI agent. Use this to see what the agent has been doing and to debug failed runs.", "operationId": "list_ai_agent_cron_runs", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "page": { "format": "int64", "minimum": 0, "type": "integer" }, "pages": { "format": "int64", "minimum": 0, "type": "integer" }, "rows": { "items": { "properties": { "agentId": { "format": "uuid", "type": "string" }, "completedAt": { "format": "date-time", "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "durationMs": { "format": "int32", "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "responsePreview": { "type": [ "string", "null" ] }, "scheduledAt": { "format": "date-time", "type": "string" }, "startedAt": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/AiAgentCronRunStatusType" } }, "required": [ "id", "agentId", "scheduledAt", "status", "createdAt" ], "type": "object" }, "type": "array" }, "total": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "rows", "total", "pages", "page" ], "type": "object" } } }, "description": "List of cron runs" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List AI agent cron runs", "tags": [ "AI Agent Cron Runs" ] }, "post": { "description": "Records a single scheduled execution of an AI agent, with its status, duration, and a preview of the response. The cron runner uses this internally \u2014 you typically only read these entries.", "operationId": "create_ai_agent_cron_run", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpCreateCronRunParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentCronRunView" } } }, "description": "Created cron run" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create AI agent cron run", "tags": [ "AI Agent Cron Runs" ] } }, "/v1/ai-agents/{agent_id}/cron-runs/{id}": { "get": { "description": "Returns a single scheduled-run record for an AI agent, including the response preview and any error captured at run time.", "operationId": "get_ai_agent_cron_run", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Cron run ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentCronRunView" } } }, "description": "Cron run details" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Get AI agent cron run", "tags": [ "AI Agent Cron Runs" ] } }, "/v1/ai-agents/{id}": { "delete": { "description": "Permanently removes an AI agent and shuts down its running runner. Pending scheduled runs are cancelled. To pause an agent without removing it, set it to inactive instead.", "operationId": "delete_ai_agent", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Deleted AI agent" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Delete AI agent", "tags": [ "AI Agents" ] }, "get": { "description": "Returns the full configuration of an AI agent \u2014 its model, skills, guardrails, channels, triggers, memory, and current status.", "operationId": "get_ai_agent", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentView" } } }, "description": "AI agent details" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Get AI agent", "tags": [ "AI Agents" ] }, "patch": { "description": "Updates an AI agent's configuration. Pass only the fields you want to change. Set the agent to inactive to pause it without deleting it.", "operationId": "update_ai_agent", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAiAgentParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentView" } } }, "description": "Updated AI agent" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Update AI agent", "tags": [ "AI Agents" ] } }, "/v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}": { "delete": { "operationId": "destroy_project_ai_runner", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "AI runner destroyed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] }, "get": { "operationId": "get_project_ai_runner_status", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRunnerView" } } }, "description": "AI runner status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] }, "post": { "operationId": "ensure_project_ai_runner", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRunnerView" } } }, "description": "AI runner ensured" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}/dashboard-password": { "get": { "operationId": "reveal_project_ai_runner_dashboard_password", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardPasswordView" } } }, "description": "Current dashboard password, decrypted for display (no restart)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}/dashboard-password/regenerate": { "post": { "operationId": "regenerate_project_ai_runner_dashboard_password", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardPasswordView" } } }, "description": "Dashboard password rotated in the pod" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}/proxy/{path}": { "post": { "operationId": "proxy_project_ai_runner", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Proxy path", "in": "path", "name": "path", "required": true, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the agent pod", "required": true }, "responses": { "200": { "description": "Proxied response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}/secrets": { "get": { "operationId": "list_project_ai_runner_secrets", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PodSecretView" }, "type": "array" } } }, "description": "Secrets listed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runner Secrets" ] }, "post": { "operationId": "create_project_ai_runner_secret", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePodSecretPayload" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodSecretView" } } }, "description": "Secret created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runner Secrets" ] } }, "/v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}/secrets/{secret_id}": { "delete": { "operationId": "delete_project_ai_runner_secret", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Secret ID", "in": "path", "name": "secret_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Secret deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runner Secrets" ] } }, "/v1/ai-runners/organizations/{org_id}/{agent_id}": { "delete": { "operationId": "destroy_org_ai_runner", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "AI runner destroyed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] }, "get": { "operationId": "get_org_ai_runner_status", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRunnerView" } } }, "description": "AI runner status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] }, "post": { "operationId": "ensure_org_ai_runner", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRunnerView" } } }, "description": "AI runner ensured" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/organizations/{org_id}/{agent_id}/dashboard-password": { "get": { "operationId": "reveal_org_ai_runner_dashboard_password", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardPasswordView" } } }, "description": "Current dashboard password, decrypted for display (no restart)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/organizations/{org_id}/{agent_id}/dashboard-password/regenerate": { "post": { "operationId": "regenerate_org_ai_runner_dashboard_password", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardPasswordView" } } }, "description": "Dashboard password rotated in the pod" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/organizations/{org_id}/{agent_id}/proxy/{path}": { "post": { "operationId": "proxy_org_ai_runner", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Proxy path", "in": "path", "name": "path", "required": true, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the agent pod", "required": true }, "responses": { "200": { "description": "Proxied response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/organizations/{org_id}/{agent_id}/secrets": { "get": { "operationId": "list_org_ai_runner_secrets", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PodSecretView" }, "type": "array" } } }, "description": "Secrets listed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runner Secrets" ] }, "post": { "operationId": "create_org_ai_runner_secret", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePodSecretPayload" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodSecretView" } } }, "description": "Secret created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runner Secrets" ] } }, "/v1/ai-runners/organizations/{org_id}/{agent_id}/secrets/{secret_id}": { "delete": { "operationId": "delete_org_ai_runner_secret", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Secret ID", "in": "path", "name": "secret_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Secret deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runner Secrets" ] } }, "/v1/ai-runners/{agent_id}": { "delete": { "operationId": "destroy_ai_runner", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "AI runner destroyed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] }, "get": { "operationId": "get_ai_runner_status", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRunnerView" } } }, "description": "AI runner status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] }, "post": { "operationId": "ensure_ai_runner", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRunnerView" } } }, "description": "AI runner ensured" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/{agent_id}/dashboard-password": { "get": { "operationId": "reveal_ai_runner_dashboard_password", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardPasswordView" } } }, "description": "Current dashboard password, decrypted for display (no restart)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/{agent_id}/dashboard-password/regenerate": { "post": { "operationId": "regenerate_ai_runner_dashboard_password", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardPasswordView" } } }, "description": "Dashboard password rotated in the pod" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/{agent_id}/proxy/{path}": { "post": { "operationId": "proxy_ai_runner", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Proxy path", "in": "path", "name": "path", "required": true, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the agent pod", "required": true }, "responses": { "200": { "description": "Proxied response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runners" ] } }, "/v1/ai-runners/{agent_id}/secrets": { "get": { "operationId": "list_ai_runner_secrets", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PodSecretView" }, "type": "array" } } }, "description": "Secrets listed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runner Secrets" ] }, "post": { "operationId": "create_ai_runner_secret", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePodSecretPayload" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodSecretView" } } }, "description": "Secret created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runner Secrets" ] } }, "/v1/ai-runners/{agent_id}/secrets/{secret_id}": { "delete": { "operationId": "delete_ai_runner_secret", "parameters": [ { "description": "AI agent ID", "in": "path", "name": "agent_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Secret ID", "in": "path", "name": "secret_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Secret deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream service unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AI Runner Secrets" ] } }, "/v1/ai-skills": { "get": { "description": "Returns the AI skills available in your account. Use pagination to navigate large result sets.", "operationId": "list_ai_skills", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_AiSkillView" } } }, "description": "Paginated list of AI skills" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:ai_skills:read" ] } ], "summary": "List AI skills", "tags": [ "AI Skills" ] }, "post": { "description": "Creates a new personal AI skill. Define the name, description, prompt content, allowed tools, and model.", "operationId": "create_ai_skill", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiSkillParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillView" } } }, "description": "Created AI skill" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:ai_skills:write" ] } ], "summary": "Create personal AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}": { "get": { "description": "Returns the AI skills available in this organization. Org-scoped skills are visible to every project in the org.", "operationId": "list_org_ai_skills", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_AiSkillView" } } }, "description": "Paginated list of organization AI skills" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "org:ai_skills:read" ] } ], "summary": "List organization AI skills", "tags": [ "AI Skills" ] }, "post": { "description": "Creates a new AI skill owned by an organization, visible to every project in the org.", "operationId": "create_org_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiSkillParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillView" } } }, "description": "Created organization AI skill" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "org:ai_skills:write" ] } ], "summary": "Create organization AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/projects/{project_id}": { "get": { "description": "Returns the AI skills available in this project. Project-scoped skills are isolated to a single project.", "operationId": "list_project_ai_skills", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_AiSkillView" } } }, "description": "Paginated list of project AI skills" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "project:ai_skills:read" ] } ], "summary": "List project AI skills", "tags": [ "AI Skills" ] }, "post": { "description": "Creates a new AI skill scoped to a single project.", "operationId": "create_project_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiSkillParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillView" } } }, "description": "Created project AI skill" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "project:ai_skills:write" ] } ], "summary": "Create project AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}": { "delete": { "description": "Permanently removes a project-scoped AI skill and every version of it. Agents that call this skill will start failing immediately.", "operationId": "delete_project_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Project AI skill deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "project:ai_skills:write" ] } ], "summary": "Delete project AI skill", "tags": [ "AI Skills" ] }, "get": { "description": "Returns the full details of a project-scoped AI skill, including its prompt, tools, current published version, and metadata.", "operationId": "get_project_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillView" } } }, "description": "Project AI skill details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "project:ai_skills:read" ] } ], "summary": "Get project AI skill", "tags": [ "AI Skills" ] }, "put": { "description": "Updates a project-scoped AI skill's draft. Publish to release the draft as a new live version.", "operationId": "update_project_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAiSkillParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillView" } } }, "description": "Updated project AI skill" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "project:ai_skills:write" ] } ], "summary": "Update project AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}/export": { "get": { "description": "Downloads the current live version of a project-scoped AI skill as a SKILL.md markdown document.", "operationId": "export_project_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "text/markdown": { "schema": { "type": "string" } } }, "description": "SKILL.md text" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "project:ai_skills:read" ] } ], "summary": "Export project AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}/publish": { "post": { "description": "Releases the current draft of a project-scoped AI skill as a new immutable live version.", "operationId": "publish_project_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillVersionView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "project:ai_skills:write" ] } ], "summary": "Publish project AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}/versions": { "get": { "description": "Returns the full version history of a project-scoped AI skill.", "operationId": "list_project_ai_skill_versions", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "in": "query", "name": "verificationStatus", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VerificationStatus" } ] } }, { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_AiSkillVersionView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "project:ai_skills:read" ] } ], "summary": "List project AI skill versions", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}/versions/{version}/yank": { "post": { "description": "Marks a published version of a project-scoped AI skill as yanked. Useful for emergency rollback after a bad release.", "operationId": "yank_project_ai_skill_version", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Version number", "in": "path", "name": "version", "required": true, "schema": { "format": "int32", "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YankBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillVersionView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "project:ai_skills:write" ] } ], "summary": "Yank project AI skill version", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/{id}": { "delete": { "description": "Permanently removes an organization-scoped AI skill and every version of it. Agents that call this skill will start failing immediately.", "operationId": "delete_org_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Organization AI skill deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "org:ai_skills:write" ] } ], "summary": "Delete organization AI skill", "tags": [ "AI Skills" ] }, "get": { "description": "Returns the full details of an organization-scoped AI skill, including its prompt, tools, current published version, and metadata.", "operationId": "get_org_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillView" } } }, "description": "Organization AI skill details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "org:ai_skills:read" ] } ], "summary": "Get organization AI skill", "tags": [ "AI Skills" ] }, "put": { "description": "Updates an organization-scoped AI skill's draft. Publish to release the draft as a new live version.", "operationId": "update_org_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAiSkillParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillView" } } }, "description": "Updated organization AI skill" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "org:ai_skills:write" ] } ], "summary": "Update organization AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/{id}/export": { "get": { "description": "Downloads the current live version of an organization-scoped AI skill as a SKILL.md markdown document.", "operationId": "export_org_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "text/markdown": { "schema": { "type": "string" } } }, "description": "SKILL.md text" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "org:ai_skills:read" ] } ], "summary": "Export organization AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/{id}/publish": { "post": { "description": "Releases the current draft of an organization-scoped AI skill as a new immutable live version.", "operationId": "publish_org_ai_skill", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillVersionView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "org:ai_skills:write" ] } ], "summary": "Publish organization AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/{id}/versions": { "get": { "description": "Returns the full version history of an organization-scoped AI skill.", "operationId": "list_org_ai_skill_versions", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "in": "query", "name": "verificationStatus", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VerificationStatus" } ] } }, { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_AiSkillVersionView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "org:ai_skills:read" ] } ], "summary": "List organization AI skill versions", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/organizations/{org_id}/{id}/versions/{version}/yank": { "post": { "description": "Marks a published version of an organization-scoped AI skill as yanked. Useful for emergency rollback after a bad release.", "operationId": "yank_org_ai_skill_version", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Version number", "in": "path", "name": "version", "required": true, "schema": { "format": "int32", "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YankBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillVersionView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "org:ai_skills:write" ] } ], "summary": "Yank organization AI skill version", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/{id}": { "delete": { "description": "Permanently removes an AI skill and every version of it. Any agent that calls this skill will start failing immediately.", "operationId": "delete_ai_skill", "parameters": [ { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } } ], "responses": { "200": { "description": "AI skill deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:ai_skills:write" ] } ], "summary": "Delete AI skill", "tags": [ "AI Skills" ] }, "get": { "description": "Returns the full details of an AI skill, including its prompt, tools, current published version, and metadata.", "operationId": "get_ai_skill", "parameters": [ { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillView" } } }, "description": "AI skill details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:ai_skills:read" ] } ], "summary": "Get AI skill", "tags": [ "AI Skills" ] }, "put": { "description": "Updates an AI skill's draft. Changes do not affect agents currently running the live version \u2014 call publish to release the draft as a new live version.", "operationId": "update_ai_skill", "parameters": [ { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAiSkillParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillView" } } }, "description": "Updated AI skill" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:ai_skills:write" ] } ], "summary": "Update AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/{id}/export": { "get": { "description": "Downloads the current live version of an AI skill as a SKILL.md markdown document. Useful for storing in source control or sharing the skill outside the platform.", "operationId": "export_ai_skill", "parameters": [ { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } } ], "responses": { "200": { "content": { "text/markdown": { "schema": { "type": "string" } } }, "description": "SKILL.md text" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:ai_skills:read" ] } ], "summary": "Export AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/{id}/publish": { "post": { "description": "Releases the current draft as a new immutable live version. Agents tracking the latest version pick up the change on their next run. Agents pinned to an earlier version are unaffected.", "operationId": "publish_ai_skill", "parameters": [ { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillVersionView" } } }, "description": "Published version" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:ai_skills:write" ] } ], "summary": "Publish AI skill", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/{id}/versions": { "get": { "description": "Returns the full version history of an AI skill. Use it to see what changed across releases or to find a specific version to pin an agent to.", "operationId": "list_ai_skill_versions", "parameters": [ { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "in": "query", "name": "verificationStatus", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VerificationStatus" } ] } }, { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_AiSkillVersionView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:ai_skills:read" ] } ], "summary": "List AI skill versions", "tags": [ "AI Skills" ] } }, "/v1/ai-skills/{id}/versions/{version}/yank": { "post": { "description": "Marks a published version as yanked so it can no longer be selected as the live version. Useful for emergency rollback after a bad release. The reason you provide is recorded for audit.", "operationId": "yank_ai_skill_version", "parameters": [ { "description": "AI skill ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Version number", "in": "path", "name": "version", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YankBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSkillVersionView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:ai_skills:write" ] } ], "summary": "Yank AI skill version", "tags": [ "AI Skills" ] } }, "/v1/authkit": { "get": { "operationId": "check_default_oauth", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Params" } } }, "required": true }, "responses": { "200": { "content": { "text/plain": { "schema": { "type": "boolean" } } }, "description": "Whether default OAuth credentials exist" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AuthKit" ] }, "post": { "operationId": "init_authkit", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareInitParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitResponse" } } }, "description": "Successfully initialized AuthKit flow" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:authkit:read" ] }, { "OAuth2": [ "org:authkit:read" ] }, { "OAuth2": [ "project:authkit:read" ] } ], "tags": [ "AuthKit" ] } }, "/v1/authkit/dashboard": { "post": { "operationId": "init_authkit_dashboard", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareInitParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitResponse" } } }, "description": "Successfully initialized AuthKit dashboard flow" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AuthKit" ] } }, "/v1/authkit/organizations/{org_id}/dashboard": { "post": { "operationId": "init_organization_authkit_dashboard", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareInitParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitResponse" } } }, "description": "Successfully initialized organization AuthKit dashboard flow" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AuthKit" ] } }, "/v1/authkit/organizations/{org_id}/projects/{project_id}/dashboard": { "post": { "operationId": "init_project_authkit_dashboard", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareInitParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitResponse" } } }, "description": "Successfully initialized project AuthKit dashboard flow" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "AuthKit" ] } }, "/v1/authkit/token": { "post": { "operationId": "generate_authkit_token", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareInitParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "description": "Successfully generated AuthKit token" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:authkit:read" ] }, { "OAuth2": [ "org:authkit:read" ] }, { "OAuth2": [ "project:authkit:read" ] } ], "tags": [ "AuthKit" ] } }, "/v1/available-actions/search/{platform}": { "get": { "description": "Free-text search across the actions on a platform. Returns the matched actions and, optionally, the knowledge documents attached to each.", "operationId": "search_actions", "parameters": [ { "description": "Platform name", "in": "path", "name": "platform", "required": true, "schema": { "type": "string" } }, { "description": "Free-text query string matched against action name / description / tags.", "in": "query", "name": "query", "required": true, "schema": { "type": "string" } }, { "description": "Maximum number of results to return.", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Include the knowledge document associated with each matched action.", "in": "query", "name": "includeKnowledge", "required": false, "schema": { "type": "boolean" } }, { "description": "Run the matched results through the execute agent for ranking.", "in": "query", "name": "executeAgent", "required": false, "schema": { "type": "boolean" } }, { "description": "Run the matched results through the knowledge agent for refinement.", "in": "query", "name": "knowledgeAgent", "required": false, "schema": { "type": "boolean" } }, { "description": "Include actions marked as deprecated.", "in": "query", "name": "includeDeprecated", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AvailableActionsWithKnowledgeView" }, "type": "array" } } }, "description": "Search results" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Search actions", "tags": [ "Actions" ] } }, "/v1/available-actions/{platform}": { "get": { "description": "Returns the actions available on a platform. Filter by action key, HTTP method, or tags to narrow the list, or include deprecated actions if you need them.", "operationId": "list_actions", "parameters": [ { "description": "Platform name", "in": "path", "name": "platform", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Filter by exact action key.", "in": "query", "name": "key", "required": false, "schema": { "type": "string" } }, { "description": "Filter by HTTP method (`get`, `post`, `put`, `patch`, `delete`).", "in": "query", "name": "method", "required": false, "schema": { "$ref": "#/components/schemas/Method" } }, { "description": "Filter by tags. Comma-separated; an action matches if it carries any one\nof them.", "in": "query", "name": "tags", "required": false, "schema": { "type": "string" } }, { "description": "Include actions marked as deprecated. Defaults to false.", "in": "query", "name": "includeDeprecated", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_AvailableActionsView" } } }, "description": "Paginated list of available actions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List actions", "tags": [ "Actions" ] } }, "/v1/available-connectors": { "get": { "description": "Returns the public catalog of connectors (platforms) available on One. Filter by platform, key, or display name. Pass `authkit=true` (with an authenticated API key) to restrict the listing to the connectors enabled for the caller's tenant in AuthKit settings.", "operationId": "list_connectors", "parameters": [ { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Filter by platform identifier (e.g. `gmail`, `shopify`).", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "Filter by exact connector key.", "in": "query", "name": "key", "required": false, "schema": { "type": "string" } }, { "description": "Filter by display name.", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "When `true`, restrict the listing to the connectors enabled for the\ncaller's tenant in AuthKit settings (scoped by project, organization,\nor user, matching the API key). Ignored for unauthenticated callers.", "in": "query", "name": "authkit", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_AvailableConnectorView" } } }, "description": "Paginated list of available connectors" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "summary": "List Connectors", "tags": [ "Connectors" ] } }, "/v1/available-connectors/connected": { "get": { "description": "Returns only the connectors the authenticated caller has actively connected in the current environment. Requires authentication.", "operationId": "list_connected_connectors", "parameters": [ { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Filter by platform identifier (e.g. `gmail`, `shopify`).", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "Filter by exact connector key.", "in": "query", "name": "key", "required": false, "schema": { "type": "string" } }, { "description": "Filter by display name.", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "When `true`, restrict the listing to the connectors enabled for the\ncaller's tenant in AuthKit settings (scoped by project, organization,\nor user, matching the API key). Ignored for unauthenticated callers.", "in": "query", "name": "authkit", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_AvailableConnectorView" } } }, "description": "Paginated list of connected connectors" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "X-One-Secret": [] } ], "summary": "List Connected Connectors", "tags": [ "Connectors" ] } }, "/v1/billings/ai-agent-seats/trial": { "get": { "description": "Reports where you stand with the one free agent-seat trial: the number of free days on offer while you are still eligible, or when a trial you are already on ends. Both fields are null once you have bought or trialed seats before. POST this same path to start the trial; buying seats never starts one.", "operationId": "get_ai_agent_seat_trial", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgentSeatTrialOffer" } } }, "description": "The trial on offer, or the one already running" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "summary": "Get the agent-seat free trial", "tags": [ "Billing" ] }, "post": { "description": "Opens a Stripe checkout for the one free agent-seat trial: a single seat, free for the period the seat price carries, charged from then on. Deliberately separate from buying seats, which always charges from day one - only the caller knows which they meant. Answers 409 when the account has already bought or trialed a seat, since the trial is once only.", "operationId": "start_ai_agent_seat_trial", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartAiAgentSeatTrialParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } }, "description": "Checkout session for the trial seat" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "summary": "Start the agent-seat free trial", "tags": [ "Billing" ] } }, "/v1/connection-definitions": { "get": { "operationId": "list_connection_definitions", "parameters": [ { "in": "query", "name": "platform", "required": false, "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "name", "required": false, "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "status", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionStatusType" } ] } }, { "in": "query", "name": "type", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConnectionType" } ] } }, { "in": "query", "name": "key", "required": false, "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "version", "required": false, "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "active", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "in": "query", "name": "inactive", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "hasOAuth", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "in": "query", "name": "showAuthentication", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ConnectionDefinitionView" } } }, "description": "Paginated list of connection definitions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection definition not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "tags": [ "Connection Definitions" ] } }, "/v1/connection-definitions/{id}": { "get": { "operationId": "retrieve_connection_definition", "parameters": [ { "description": "Connection definition ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/ConnectionDefinitionId" } }, { "in": "query", "name": "showAuthentication", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionDefinitionView" } } }, "description": "Connection definition" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection definition not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "tags": [ "Connection Definitions" ] } }, "/v1/connection-oauth-definitions": { "get": { "operationId": "list_connection_oauth_definitions", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ConnectionOAuthDefinitionView" } } }, "description": "Paginated list of connection OAuth definitions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection OAuth definition" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection definition not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "tags": [ "Connection OAuth Definitions" ] } }, "/v1/connection-oauth-definitions/view/id/{id}": { "get": { "operationId": "retrieve_connection_oauth_definition_by_id", "parameters": [ { "description": "Connection OAuth definition ID", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/ConnectionOAuthDefinitionId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionOAuthDefinitionView" } } }, "description": "Connection OAuth definition" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection OAuth definition" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection definition not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "tags": [ "Connection OAuth Definitions" ] } }, "/v1/connection-oauth-definitions/view/{platform}": { "get": { "operationId": "retrieve_connection_oauth_definition_by_platform", "parameters": [ { "description": "Platform name", "in": "path", "name": "platform", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionOAuthDefinitionView" } } }, "description": "Connection OAuth definition" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection OAuth definition" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection definition not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "tags": [ "Connection OAuth Definitions" ] } }, "/v1/connections": { "get": { "operationId": "list_connections", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ConnectionView" } } }, "description": "Paginated list of connections" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:connections:read" ] }, { "OAuth2": [ "org:connections:read" ] }, { "OAuth2": [ "project:connections:read" ] } ], "tags": [ "Connections" ] } }, "/v1/connections/metrics": { "get": { "operationId": "get_connection_metrics", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionMetrics" } } }, "description": "Connection metrics" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "Connections" ] } }, "/v1/connections/organizations/{org_id}": { "get": { "operationId": "list_organization_connections", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ConnectionView" } } }, "description": "Paginated list of organization connections" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "org:connections:read" ] } ], "tags": [ "Connections" ] } }, "/v1/connections/organizations/{org_id}/projects/{project_id}": { "get": { "operationId": "list_project_connections", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ConnectionView" } } }, "description": "Paginated list of project connections" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "project:connections:read" ] } ], "tags": [ "Connections" ] } }, "/v1/connections/organizations/{org_id}/projects/{project_id}/{id}": { "delete": { "operationId": "delete_project_connection", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Project connection deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "project:connections:write" ] } ], "tags": [ "Connections" ] }, "get": { "operationId": "retrieve_project_connection", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionView" } } }, "description": "Project connection details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "project:connections:read" ] } ], "tags": [ "Connections" ] }, "patch": { "operationId": "update_project_connection_tags", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConnection" } } }, "required": true }, "responses": { "200": { "description": "Project connection tags updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "project:connections:write" ] } ], "tags": [ "Connections" ] } }, "/v1/connections/organizations/{org_id}/{id}": { "delete": { "operationId": "delete_organization_connection", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Organization connection deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "org:connections:write" ] } ], "tags": [ "Connections" ] }, "get": { "operationId": "retrieve_organization_connection", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionView" } } }, "description": "Organization connection details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "org:connections:read" ] } ], "tags": [ "Connections" ] }, "patch": { "operationId": "update_organization_connection_tags", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConnection" } } }, "required": true }, "responses": { "200": { "description": "Organization connection tags updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "org:connections:write" ] } ], "tags": [ "Connections" ] } }, "/v1/connections/reachable": { "get": { "description": "Lists every connection the caller's grant reaches - the connections it can read plus the ones it can only run a custom action on - each labelled with the access it confers. A connection the grant cannot read carries only its key, connector and access label, never the connection record.", "operationId": "list_reachable_connections", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ReachableConnectionView" } } }, "description": "Paginated reachable connections, each with its access label" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "Bearer": [] }, { "Session": [] }, { "OAuth2": [ "user:connections:read" ] }, { "OAuth2": [ "org:connections:read" ] }, { "OAuth2": [ "project:connections:read" ] } ], "summary": "List reachable connections", "tags": [ "Connections" ] } }, "/v1/connections/{id}": { "delete": { "operationId": "delete_connection", "parameters": [ { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Connection deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "tags": [ "Connections" ] }, "get": { "operationId": "retrieve_connection", "parameters": [ { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionView" } } }, "description": "Connection details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:connections:read" ] }, { "OAuth2": [ "org:connections:read" ] }, { "OAuth2": [ "project:connections:read" ] } ], "tags": [ "Connections" ] }, "patch": { "operationId": "update_connection_tags", "parameters": [ { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConnection" } } }, "required": true }, "responses": { "200": { "description": "Connection tags updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "tags": [ "Connections" ] } }, "/v1/event-access": { "get": { "operationId": "list_event_access", "parameters": [ { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Optional, and **ignored for a bearer** - `pinned_environment`\nsubstitutes the token's own.\n\nDefaulted, unlike its counterpart on the create bodies, because the two\nare different questions: here the value narrows a listing, and the\ndefault narrows it to `test`, which is visible in the rows that come\nback. There it decides which environment a new key is minted for, where\na silently defaulted value is a wrong key rather than a wrong page.", "in": "query", "name": "environment", "required": false, "schema": { "$ref": "#/components/schemas/SecretKeyEnvironment" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_EventAccessView" } } }, "description": "Paginated list of event access keys" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "OAuth2": [ "user:secrets:read" ] } ], "tags": [ "Event Access" ] }, "post": { "operationId": "create_event_access", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Params" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventAccessView" } } }, "description": "Created event access key" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "OAuth2": [ "user:secrets:write" ] } ], "tags": [ "Event Access" ] } }, "/v1/event-access/organizations/{org_id}": { "get": { "operationId": "list_organization_event_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Optional, and **ignored for a bearer** - `pinned_environment`\nsubstitutes the token's own.\n\nDefaulted, unlike its counterpart on the create bodies, because the two\nare different questions: here the value narrows a listing, and the\ndefault narrows it to `test`, which is visible in the rows that come\nback. There it decides which environment a new key is minted for, where\na silently defaulted value is a wrong key rather than a wrong page.", "in": "query", "name": "environment", "required": false, "schema": { "$ref": "#/components/schemas/SecretKeyEnvironment" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_OrganizationEventAccessView" } } }, "description": "Paginated list of organization event access keys" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "OAuth2": [ "org:secrets:read" ] } ], "summary": "\n\n---\n\n## Autometrics\n\nView the live metrics for the `list_organization_keys` function:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20the%20%60list%5Forganization%5Fkeys%60%20function%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22list%5Forganization%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20the%20%60list%5Forganization%5Fkeys%60%20function%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22list%5Forganization%5Fkeys%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22list%5Forganization%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)\n- [Latency (95th and 99th percentiles)](http://localhost:9090/graph?g0.expr=%23%2095th%20and%2099th%20percentile%20latencies%20%28in%20seconds%29%20for%20the%20%60list%5Forganization%5Fkeys%60%20function%0A%0Alabel%5Freplace%28histogram%5Fquantile%280%2E99%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22list%5Forganization%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2299%22%2C%20%22%22%2C%20%22%22%29%0Aor%0Alabel%5Freplace%28histogram%5Fquantile%280%2E95%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22list%5Forganization%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2295%22%2C%20%22%22%2C%20%22%22%29&g0.tab=0)\n\nOr, dig into the metrics of *functions called by* `list_organization_keys`:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20functions%20called%20by%20%60list%5Forganization%5Fkeys%60%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22list%5Forganization%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20functions%20called%20by%20%60list%5Forganization%5Fkeys%60%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22list%5Forganization%5Fkeys%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22list%5Forganization%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)", "tags": [ "Event Access" ] }, "post": { "operationId": "create_organization_event_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEventAccessParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEventAccessView" } } }, "description": "Created organization event access key" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "OAuth2": [ "org:secrets:write" ] } ], "summary": "\n\n---\n\n## Autometrics\n\nView the live metrics for the `create_organization_key` function:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20the%20%60create%5Forganization%5Fkey%60%20function%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22create%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20the%20%60create%5Forganization%5Fkey%60%20function%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22create%5Forganization%5Fkey%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22create%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)\n- [Latency (95th and 99th percentiles)](http://localhost:9090/graph?g0.expr=%23%2095th%20and%2099th%20percentile%20latencies%20%28in%20seconds%29%20for%20the%20%60create%5Forganization%5Fkey%60%20function%0A%0Alabel%5Freplace%28histogram%5Fquantile%280%2E99%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22create%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2299%22%2C%20%22%22%2C%20%22%22%29%0Aor%0Alabel%5Freplace%28histogram%5Fquantile%280%2E95%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22create%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2295%22%2C%20%22%22%2C%20%22%22%29&g0.tab=0)\n\nOr, dig into the metrics of *functions called by* `create_organization_key`:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20functions%20called%20by%20%60create%5Forganization%5Fkey%60%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22create%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20functions%20called%20by%20%60create%5Forganization%5Fkey%60%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22create%5Forganization%5Fkey%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22create%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)", "tags": [ "Event Access" ] } }, "/v1/event-access/organizations/{org_id}/projects/{project_id}": { "get": { "operationId": "list_project_event_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Optional, and **ignored for a bearer** - `pinned_environment`\nsubstitutes the token's own.\n\nDefaulted, unlike its counterpart on the create bodies, because the two\nare different questions: here the value narrows a listing, and the\ndefault narrows it to `test`, which is visible in the rows that come\nback. There it decides which environment a new key is minted for, where\na silently defaulted value is a wrong key rather than a wrong page.", "in": "query", "name": "environment", "required": false, "schema": { "$ref": "#/components/schemas/SecretKeyEnvironment" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_OrganizationEventAccessView" } } }, "description": "Paginated list of project event access keys" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "OAuth2": [ "project:secrets:read" ] } ], "summary": "\n\n---\n\n## Autometrics\n\nView the live metrics for the `list_project_keys` function:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20the%20%60list%5Fproject%5Fkeys%60%20function%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22list%5Fproject%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20the%20%60list%5Fproject%5Fkeys%60%20function%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22list%5Fproject%5Fkeys%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22list%5Fproject%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)\n- [Latency (95th and 99th percentiles)](http://localhost:9090/graph?g0.expr=%23%2095th%20and%2099th%20percentile%20latencies%20%28in%20seconds%29%20for%20the%20%60list%5Fproject%5Fkeys%60%20function%0A%0Alabel%5Freplace%28histogram%5Fquantile%280%2E99%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22list%5Fproject%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2299%22%2C%20%22%22%2C%20%22%22%29%0Aor%0Alabel%5Freplace%28histogram%5Fquantile%280%2E95%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22list%5Fproject%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2295%22%2C%20%22%22%2C%20%22%22%29&g0.tab=0)\n\nOr, dig into the metrics of *functions called by* `list_project_keys`:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20functions%20called%20by%20%60list%5Fproject%5Fkeys%60%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22list%5Fproject%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20functions%20called%20by%20%60list%5Fproject%5Fkeys%60%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22list%5Fproject%5Fkeys%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22list%5Fproject%5Fkeys%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)", "tags": [ "Event Access" ] }, "post": { "operationId": "create_project_event_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEventAccessParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEventAccessView" } } }, "description": "Created project event access key" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "OAuth2": [ "project:secrets:write" ] } ], "summary": "\n\n---\n\n## Autometrics\n\nView the live metrics for the `create_project_key` function:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20the%20%60create%5Fproject%5Fkey%60%20function%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22create%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20the%20%60create%5Fproject%5Fkey%60%20function%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22create%5Fproject%5Fkey%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22create%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)\n- [Latency (95th and 99th percentiles)](http://localhost:9090/graph?g0.expr=%23%2095th%20and%2099th%20percentile%20latencies%20%28in%20seconds%29%20for%20the%20%60create%5Fproject%5Fkey%60%20function%0A%0Alabel%5Freplace%28histogram%5Fquantile%280%2E99%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22create%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2299%22%2C%20%22%22%2C%20%22%22%29%0Aor%0Alabel%5Freplace%28histogram%5Fquantile%280%2E95%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22create%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2295%22%2C%20%22%22%2C%20%22%22%29&g0.tab=0)\n\nOr, dig into the metrics of *functions called by* `create_project_key`:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20functions%20called%20by%20%60create%5Fproject%5Fkey%60%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22create%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20functions%20called%20by%20%60create%5Fproject%5Fkey%60%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22create%5Fproject%5Fkey%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22create%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)", "tags": [ "Event Access" ] } }, "/v1/event-access/organizations/{org_id}/projects/{project_id}/{key_id}": { "delete": { "operationId": "delete_project_event_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "key_id", "required": true, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Key deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "OAuth2": [ "project:secrets:write" ] } ], "summary": "\n\n---\n\n## Autometrics\n\nView the live metrics for the `delete_project_key` function:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20the%20%60delete%5Fproject%5Fkey%60%20function%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22delete%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20the%20%60delete%5Fproject%5Fkey%60%20function%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22delete%5Fproject%5Fkey%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22delete%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)\n- [Latency (95th and 99th percentiles)](http://localhost:9090/graph?g0.expr=%23%2095th%20and%2099th%20percentile%20latencies%20%28in%20seconds%29%20for%20the%20%60delete%5Fproject%5Fkey%60%20function%0A%0Alabel%5Freplace%28histogram%5Fquantile%280%2E99%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22delete%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2299%22%2C%20%22%22%2C%20%22%22%29%0Aor%0Alabel%5Freplace%28histogram%5Fquantile%280%2E95%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22delete%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2295%22%2C%20%22%22%2C%20%22%22%29&g0.tab=0)\n\nOr, dig into the metrics of *functions called by* `delete_project_key`:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20functions%20called%20by%20%60delete%5Fproject%5Fkey%60%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22delete%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20functions%20called%20by%20%60delete%5Fproject%5Fkey%60%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22delete%5Fproject%5Fkey%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22delete%5Fproject%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)", "tags": [ "Event Access" ] } }, "/v1/event-access/organizations/{org_id}/{key_id}": { "delete": { "operationId": "delete_organization_event_access", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "key_id", "required": true, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Key deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "OAuth2": [ "org:secrets:write" ] } ], "summary": "\n\n---\n\n## Autometrics\n\nView the live metrics for the `delete_organization_key` function:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20the%20%60delete%5Forganization%5Fkey%60%20function%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22delete%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20the%20%60delete%5Forganization%5Fkey%60%20function%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22delete%5Forganization%5Fkey%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Cfunction%3D%22delete%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)\n- [Latency (95th and 99th percentiles)](http://localhost:9090/graph?g0.expr=%23%2095th%20and%2099th%20percentile%20latencies%20%28in%20seconds%29%20for%20the%20%60delete%5Forganization%5Fkey%60%20function%0A%0Alabel%5Freplace%28histogram%5Fquantile%280%2E99%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22delete%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2299%22%2C%20%22%22%2C%20%22%22%29%0Aor%0Alabel%5Freplace%28histogram%5Fquantile%280%2E95%2C%20sum%20by%20%28le%2C%20function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%5Fduration%28%5Fseconds%29%3F%5Fbucket%22%2Cfunction%3D%22delete%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%2C%20%22percentile%5Flatency%22%2C%20%2295%22%2C%20%22%22%2C%20%22%22%29&g0.tab=0)\n\nOr, dig into the metrics of *functions called by* `delete_organization_key`:\n- [Request Rate](http://localhost:9090/graph?g0.expr=%23%20Rate%20of%20calls%20to%20functions%20called%20by%20%60delete%5Forganization%5Fkey%60%20per%20second%2C%20averaged%20over%205%20minute%20windows%0A%0Asum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22delete%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29&g0.tab=0)\n- [Error Ratio](http://localhost:9090/graph?g0.expr=%23%20Percentage%20of%20calls%20to%20functions%20called%20by%20%60delete%5Forganization%5Fkey%60%20that%20return%20errors%2C%20averaged%20over%205%20minute%20windows%0A%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22delete%5Forganization%5Fkey%22%2Cresult%3D%22error%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29%0A%2F%0A%28sum%20by%20%28function%2C%20module%2C%20service%5Fname%2C%20commit%2C%20version%29%20%28rate%28%7B%5F%5Fname%5F%5F%3D%7E%22function%5Fcalls%28%5Fcount%29%3F%28%5Ftotal%29%3F%22%2Ccaller%5Ffunction%3D%22delete%5Forganization%5Fkey%22%7D%5B5m%5D%29%20%2A%20on%20%28instance%2C%20job%29%20group%5Fleft%28version%2C%20commit%29%20last%5Fover%5Ftime%28build%5Finfo%5B1s%5D%29%29%29&g0.tab=0)", "tags": [ "Event Access" ] } }, "/v1/event-access/{id}": { "delete": { "operationId": "delete_event_access", "parameters": [ { "description": "Event access key ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Key deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] }, { "OAuth2": [ "user:secrets:write" ] } ], "tags": [ "Event Access" ] } }, "/v1/knowledge": { "get": { "description": "Returns knowledge documents \u2014 the per-action context the platform uses to ground LLM calls. Filter by platform or by a specific action to narrow the result.", "operationId": "list_knowledge", "parameters": [ { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Filter by the connector / platform the knowledge document is attached\nto.", "in": "query", "name": "connectionPlatform", "required": false, "schema": { "type": "string" } }, { "description": "Filter by the action / system id (`_id` on the wire) the knowledge\ndocument is attached to.", "in": "query", "name": "_id", "required": false, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_KnowledgeView" } } }, "description": "Paginated list of knowledge items" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:connections:read" ] }, { "OAuth2": [ "org:connections:read" ] }, { "OAuth2": [ "project:connections:read" ] } ], "summary": "List knowledge", "tags": [ "Knowledge" ] } }, "/v1/link-invitations/organizations/{org_id}": { "get": { "operationId": "list_link_invitations", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "accepted", "expired" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_LinkInvitationView" } } }, "description": "List of link invitations" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link Invitations" ] }, "post": { "operationId": "send_link_invitation", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResponse" } } }, "description": "Link invitation sent" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link Invitations" ] } }, "/v1/link-invitations/organizations/{org_id}/{id}": { "delete": { "operationId": "revoke_link_invitation", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Link invitation ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Link invitation revoked" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link Invitations" ] } }, "/v1/link-invitations/organizations/{org_id}/{id}/resend": { "post": { "operationId": "resend_link_invitation", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Link invitation ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkInvitationView" } } }, "description": "Link invitation resent" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link Invitations" ] } }, "/v1/link-templates/organizations/{org_id}": { "get": { "operationId": "list_link_templates", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_LinkTemplateView" } } }, "description": "List of link templates" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link Templates" ] }, "post": { "operationId": "create_link_template", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkTemplateView" } } }, "description": "Link template created" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link Templates" ] } }, "/v1/link-templates/organizations/{org_id}/{id}": { "delete": { "operationId": "delete_link_template", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Link template ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Link template deleted" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link Templates" ] }, "get": { "operationId": "retrieve_link_template", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Link template ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkTemplateView" } } }, "description": "Link template details" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link Templates" ] }, "put": { "operationId": "update_link_template", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Link template ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkTemplateView" } } }, "description": "Link template updated" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link Templates" ] } }, "/v1/link/connections": { "get": { "operationId": "list_link_connections", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ConnectionView" } } }, "description": "Connections owned by the invitation's project" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "tags": [ "Link" ] } }, "/v1/link/init": { "post": { "operationId": "init_link_connection", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareInitParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitResponse" } } }, "description": "Connection initialized" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "tags": [ "Link" ] } }, "/v1/link/organizations/{org_id}/{id}": { "get": { "operationId": "retrieve_link", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Link ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveResponse" } } }, "description": "Link details + activated connectors" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link" ] } }, "/v1/link/organizations/{org_id}/{id}/rotate": { "post": { "operationId": "rotate_link", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Link ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateResponse" } } }, "description": "Link API key rotated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "Link" ] } }, "/v1/link/resolve": { "get": { "operationId": "resolve_link", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResponse" } } }, "description": "Resolved invitation + connector entries" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource already exists" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "tags": [ "Link" ] } }, "/v1/management/organizations/setup": { "post": { "description": "Create a new organization and mint a service-account API key for it in a single call. Accepts any regular API key or a session cookie; the returned key is what subsequent /v1/management/* calls for this organization use.", "operationId": "setup_organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupOrganizationParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupOrganizationResponse" } } }, "description": "Organization created with a new service-account API key" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Setup Organization", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}": { "delete": { "description": "Soft-delete an organization. The caller must authenticate with the organization's service-account key. Fails with 409 if any projects exist in the organization or if any org-level connections are active \u2014 those must be cleaned up first. As part of the cascade, every active org-scoped API key (including the service-account key itself) is revoked.", "operationId": "delete_organization", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationView" } } }, "description": "Organization soft-deleted; all org-scoped keys revoked" }, "404": { "description": "Organization not found" }, "409": { "description": "Organization has projects or active org-level connections" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Delete Organization", "tags": [ "Organizations" ] }, "get": { "description": "Fetch settings for an organization, including its members and projects.", "operationId": "get_organization", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSettingsView" } } }, "description": "Organization settings with embedded members and projects" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Get Organization", "tags": [ "Organizations" ] }, "put": { "description": "Update the name or description of an organization.", "operationId": "update_organization_settings", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "Updated tenant description", "name": "Acme Corp" }, "schema": { "$ref": "#/components/schemas/UpdateOrganizationSettingsParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSettingsView" } } }, "description": "Updated organization settings" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Update Organization Settings", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/authkit": { "put": { "description": "Create or update the Embeddable Auth (OAuth provider) configuration at the organization level.", "operationId": "upsert_organization_authkit", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOrganizationAuthKitParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedPlatformView" } } }, "description": "Embeddable Auth row created or updated" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Configure Organization Embeddable Auth", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/invitations": { "get": { "description": "Return a paginated list of pending invitations for this organization.", "operationId": "list_organization_invitations", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_InvitationView" } } }, "description": "Paginated list of invitations" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List Organization Invitations", "tags": [ "Organizations" ] }, "post": { "description": "Invite someone to join this organization by email.", "operationId": "create_organization_invitation", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationView" } } }, "description": "Invitation created, or matching active invitation returned" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create Organization Invitation", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/invitations/{invitation_id}": { "delete": { "description": "Cancel a pending organization or project invitation under this org.", "operationId": "revoke_organization_invitation", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Invitation ID", "in": "path", "name": "invitation_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationView" } } }, "description": "Invitation revoked" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Revoke Organization Invitation", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/invitations/{invitation_id}/resend": { "post": { "description": "Rotate the token on a pending invitation and resend the invitation email.", "operationId": "resend_organization_invitation", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Invitation ID", "in": "path", "name": "invitation_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationView" } } }, "description": "Invitation resent with a freshly rotated token" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Resend Organization Invitation", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/keys": { "get": { "description": "Return a paginated list of API keys scoped to this organization, filtered to the environment of the calling service-account key. The list includes the organization's service-account key alongside any keys minted via Create Organization Key.", "operationId": "list_organization_keys", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_OrganizationEventAccessView" } } }, "description": "Paginated list of organization-scoped API keys" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List Organization Keys", "tags": [ "Organizations" ] }, "post": { "description": "Mint an additional API key scoped to this organization.", "operationId": "create_organization_key", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationKeyParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEventAccessView" } } }, "description": "Organization-scoped API key created" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create Organization Key", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/keys/{key_id}": { "delete": { "description": "Revoke an organization-scoped API key created via Create Organization Key. The organization's service-account key cannot be deleted through this endpoint; revoke it by deleting the organization itself. The caller must authenticate with the organization's service-account key \u2014 other organization keys are not accepted.", "operationId": "delete_organization_key", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "key_id", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "description": "Organization-scoped key revoked" }, "403": { "description": "Target key is a service-account key and cannot be deleted via this endpoint" }, "404": { "description": "Key not found in this organization" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Delete Organization Key", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/keys/{key_id}/configure": { "put": { "description": "Replace the passthrough access rules on an organization-scoped API key. The configured `methods` and `rules` are evaluated ONLY when the key is used to call the passthrough API \u2014 they do NOT gate first-party endpoints such as /v1/connections/* CRUD, webhooks, vault, etc., which continue to be authorized by the key's role and tenancy. Use this endpoint to narrow which external-platform calls the key can proxy.", "operationId": "configure_organization_key", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "key_id", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "methods": [ "GET", "POST" ], "rules": [ { "actionIds": [ "act_01HXXXXXXXXXXXXXXXXXXXXXXX" ], "connectionKey": "live::gmail::default", "methods": [ "GET" ], "type": "connection" } ] }, "schema": { "$ref": "#/components/schemas/ConfigureAccessParams" } } }, "required": true }, "responses": { "200": { "description": "Access rules replaced on the target key" }, "404": { "description": "Key not found in this organization" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Configure Organization Key Access", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/members": { "get": { "description": "Return a paginated list of users who belong to this organization.", "operationId": "list_organization_members", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ManagementOrganizationMemberView" } } }, "description": "Paginated list of organization members" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List Organization Members", "tags": [ "Organizations" ] }, "put": { "description": "Change the role assigned to a user in this organization.", "operationId": "update_organization_member_role", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementOrganizationMemberView" } } }, "description": "Updated member" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Update Organization Member Role", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/members/{user_id}": { "delete": { "description": "Remove a user from the organization. The underlying user account stays intact.", "operationId": "remove_organization_member", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "User ID of the member to remove", "in": "path", "name": "user_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveMemberResponse" } } }, "description": "Member removed" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Remove Organization Member", "tags": [ "Organizations" ] } }, "/v1/management/organizations/{org_id}/projects": { "get": { "description": "Return a paginated list of projects in this organization.", "operationId": "list_projects", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ProjectView" } } }, "description": "Paginated list of projects" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List Projects", "tags": [ "Projects" ] }, "post": { "description": "Create a new project inside an organization. Optionally mints a project-scoped API key in the same call when `mintKey: true` is sent in the body; the key (if minted) is returned alongside the project.", "operationId": "create_project", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "Customer-facing production project", "keyName": "acme-prod", "mintKey": true, "name": "Production" }, "schema": { "$ref": "#/components/schemas/CreateProjectParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectResponse" } } }, "description": "Project created (and key minted when requested)" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create Project", "tags": [ "Projects" ] } }, "/v1/management/organizations/{org_id}/projects/{project_id}": { "delete": { "description": "Soft-delete a project. Fails if the project still has active connections.", "operationId": "delete_project", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectView" } } }, "description": "Project deleted" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Delete Project", "tags": [ "Projects" ] }, "put": { "description": "Update the name or description of a project.", "operationId": "update_project", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "Updated project description", "name": "Production" }, "schema": { "$ref": "#/components/schemas/UpdateProjectParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectView" } } }, "description": "Updated project" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Update Project", "tags": [ "Projects" ] } }, "/v1/management/organizations/{org_id}/projects/{project_id}/authkit": { "put": { "description": "Create or update the Embeddable Auth (OAuth provider) configuration scoped to a specific project. Same body shape as the organization-level endpoint; the difference is that this row is bound to one project rather than the whole organization.", "operationId": "upsert_project_authkit", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOrganizationAuthKitParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedPlatformView" } } }, "description": "Embeddable Auth row created or updated" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Configure Project Embeddable Auth", "tags": [ "Projects" ] } }, "/v1/management/organizations/{org_id}/projects/{project_id}/invitations": { "get": { "description": "Return a paginated list of pending invitations for this project.", "operationId": "list_project_invitations", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_InvitationView" } } }, "description": "Paginated list of project invitations" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List Project Invitations", "tags": [ "Projects" ] }, "post": { "description": "Invite someone to join a specific project by email.", "operationId": "create_project_invitation", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationView" } } }, "description": "Project invitation created" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create Project Invitation", "tags": [ "Projects" ] } }, "/v1/management/organizations/{org_id}/projects/{project_id}/keys": { "get": { "description": "Return a paginated list of API keys scoped to this project, filtered to the environment of the calling service-account key.", "operationId": "list_project_keys", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_OrganizationEventAccessView" } } }, "description": "Paginated list of project-scoped API keys" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List Project Keys", "tags": [ "Projects" ] }, "post": { "description": "Mint an additional API key scoped to a specific project.", "operationId": "create_project_key", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectKeyParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEventAccessView" } } }, "description": "Project-scoped API key created. The accessKey field is the only point at which the full secret is exposed." } }, "security": [ { "X-One-Secret": [] } ], "summary": "Create Project Key", "tags": [ "Projects" ] } }, "/v1/management/organizations/{org_id}/projects/{project_id}/keys/{key_id}": { "delete": { "description": "Revoke a project-scoped API key created via Create Project Key. Service-account keys cannot be deleted through this endpoint. The caller must authenticate with the organization's service-account key \u2014 project keys are not accepted.", "operationId": "delete_project_key", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "key_id", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "description": "Project-scoped key revoked" }, "403": { "description": "Target key is a service-account key and cannot be deleted via this endpoint" }, "404": { "description": "Key not found in this project" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Delete Project Key", "tags": [ "Projects" ] } }, "/v1/management/organizations/{org_id}/projects/{project_id}/keys/{key_id}/configure": { "put": { "description": "Replace the passthrough access rules on a project-scoped API key. Same scope and semantics as Configure Organization Key Access: `methods` and `rules` apply ONLY to passthrough API calls and do NOT gate first-party endpoints.", "operationId": "configure_project_key", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Event access key ID", "in": "path", "name": "key_id", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "methods": [ "GET", "POST" ], "rules": [ { "actionIds": [ "act_01HXXXXXXXXXXXXXXXXXXXXXXX" ], "connectionKey": "live::gmail::default", "methods": [ "GET" ], "type": "connection" } ] }, "schema": { "$ref": "#/components/schemas/ConfigureAccessParams" } } }, "required": true }, "responses": { "200": { "description": "Access rules replaced on the target key" }, "404": { "description": "Key not found in this project" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Configure Project Key Access", "tags": [ "Projects" ] } }, "/v1/management/organizations/{org_id}/projects/{project_id}/members": { "get": { "description": "Return a paginated list of users who belong to this project.", "operationId": "list_project_members", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ManagementProjectMemberView" } } }, "description": "Paginated list of project members" } }, "security": [ { "X-One-Secret": [] } ], "summary": "List Project Members", "tags": [ "Projects" ] }, "put": { "description": "Change the role assigned to a user in this project.", "operationId": "update_project_member_role", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementProjectMemberView" } } }, "description": "Updated project member" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Update Project Member Role", "tags": [ "Projects" ] } }, "/v1/management/organizations/{org_id}/projects/{project_id}/members/{user_id}": { "delete": { "description": "Remove a user from a project. The user keeps their organization-level membership.", "operationId": "remove_project_member", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "User ID of the member to remove", "in": "path", "name": "user_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveMemberResponse" } } }, "description": "Project member removed" } }, "security": [ { "X-One-Secret": [] } ], "summary": "Remove Project Member", "tags": [ "Projects" ] } }, "/v1/marketplace/ai-skills": { "get": { "operationId": "search_marketplace_ai_skills", "parameters": [ { "in": "query", "name": "q", "required": false, "schema": { "type": [ "string", "null" ] } }, { "in": "query", "name": "verifiedOnly", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_MarketplaceSkillView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "Marketplace" ] } }, "/v1/marketplace/ai-skills/{id}": { "get": { "operationId": "get_marketplace_ai_skill_latest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceSkillView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "Marketplace" ] } }, "/v1/marketplace/ai-skills/{id}/versions": { "get": { "operationId": "list_marketplace_ai_skill_versions", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_MarketplaceSkillView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "Marketplace" ] } }, "/v1/marketplace/ai-skills/{id}/versions/{version}": { "get": { "operationId": "get_marketplace_ai_skill_version", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "in": "path", "name": "version", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceSkillView" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "Marketplace" ] } }, "/v1/marketplace/ai-skills/{id}/versions/{version}/export": { "get": { "operationId": "export_marketplace_ai_skill_version", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/AiSkillId" } }, { "in": "path", "name": "version", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "text/markdown": { "schema": { "type": "string" } } }, "description": "SKILL.md text" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource state does not allow this action" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "Marketplace" ] } }, "/v1/oauth-authorizations": { "get": { "operationId": "list_oauth_authorizations", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_OAuthAuthorizationView" } } }, "description": "Apps the caller has authorized" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Authorizations" ] } }, "/v1/oauth-authorizations/{client_id}": { "delete": { "operationId": "revoke_oauth_authorization", "parameters": [ { "description": "OAuth client to revoke", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthRevokeAuthorizationResponse" } } }, "description": "Access and refresh tokens revoked" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Authorizations" ] }, "get": { "operationId": "read_oauth_authorization", "parameters": [ { "description": "OAuth client to read", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AuthorizationReachView" }, "type": "array" } } }, "description": "What the app reaches, one entry per environment" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Authorizations" ] }, "patch": { "operationId": "edit_oauth_authorization", "parameters": [ { "description": "OAuth client to edit", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AuthorizationReachView" }, "type": "array" } } }, "description": "What the app reaches after the edit" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Authorizations" ] } }, "/v1/oauth-clients": { "get": { "operationId": "list_oauth_clients", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_OAuthClientView" } } }, "description": "OAuth clients owned by the caller" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] }, "post": { "operationId": "create_oauth_client", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientCreatedView" } } }, "description": "OAuth client created; the plain secret is shown once" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] } }, "/v1/oauth-clients/{client_id}": { "delete": { "operationId": "delete_oauth_client", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth client deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] }, "get": { "operationId": "retrieve_oauth_client", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientView" } } }, "description": "OAuth client details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] }, "patch": { "operationId": "update_oauth_client", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientView" } } }, "description": "OAuth client updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] } }, "/v1/oauth-clients/{client_id}/permission-sets": { "get": { "operationId": "list_permission_sets", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_OAuthPermissionSetView" } } }, "description": "The client's permission sets, without connector resolution" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] }, "post": { "operationId": "create_permission_set", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionSetBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionSetDetailView" } } }, "description": "Permission set created, with its connectors resolved" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] } }, "/v1/oauth-clients/{client_id}/permission-sets/{id}": { "delete": { "operationId": "delete_permission_set", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "description": "Permission set ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Permission set retired; grants already made are untouched" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] }, "get": { "operationId": "retrieve_permission_set", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "description": "Permission set ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionSetDetailView" } } }, "description": "Permission set with its connectors resolved" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] }, "patch": { "operationId": "update_permission_set", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "description": "Permission set ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionSetBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionSetDetailView" } } }, "description": "Permission set updated, with its connectors resolved; grants already made are untouched" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] } }, "/v1/oauth-clients/{client_id}/secret": { "post": { "operationId": "regenerate_oauth_client_secret", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretView" } } }, "description": "New client secret; shown once and never recoverable" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] } }, "/v1/oauth-clients/{client_id}/users": { "get": { "operationId": "list_oauth_client_users", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_ClientUserView" } } }, "description": "Users who authorized this client" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] } }, "/v1/oauth-clients/{client_id}/users/{user_id}": { "delete": { "operationId": "revoke_oauth_client_user", "parameters": [ { "description": "Public OAuth client ID", "in": "path", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "description": "User whose access is revoked", "in": "path", "name": "user_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthRevokeAuthorizationResponse" } } }, "description": "Tokens revoked" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many requests" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "Session": [] } ], "tags": [ "OAuth Clients" ] } }, "/v1/passthrough/{key}": { "delete": { "description": "Forwards an arbitrary HTTP request to the upstream platform. The method, URL path, query parameters, and body are all preserved \u2014 credentials are resolved from your connection and signed in automatically. Use this when no first-class action exists for what you need to do on the platform.", "operationId": "passthrough", "parameters": [ { "description": "API path forwarded to the destination platform (e.g. `users/me`, `contacts`). Anything after `/v1/passthrough/` is preserved verbatim as the upstream path. Generated clients must URL-encode any `/` within a single segment as `%2F` (e.g. `users%2Fme`), since an OpenAPI path parameter cannot contain a raw slash.", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "The action's system_id (from `/v1/available-actions`). Selects which connection-model definition resolves the upstream call. This is what the SDK's `triggerAction` sets.", "in": "header", "name": "X-One-Action-Id", "required": true, "schema": { "type": "string" } }, { "description": "The connection to run against. Required whichever credential you present: it selects the connection, it does not authenticate you, and a request without it is refused before the handler runs.", "in": "header", "name": "X-One-Connection-Key", "required": true, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the destination API. Sent as-is to the upstream platform with the request's content-type preserved.", "required": true }, "responses": { "200": { "description": "Response proxied back from the destination API" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "summary": "Passthrough request", "tags": [ "Passthrough" ] }, "get": { "description": "Forwards an arbitrary HTTP request to the upstream platform. The method, URL path, query parameters, and body are all preserved \u2014 credentials are resolved from your connection and signed in automatically. Use this when no first-class action exists for what you need to do on the platform.", "operationId": "passthrough", "parameters": [ { "description": "API path forwarded to the destination platform (e.g. `users/me`, `contacts`). Anything after `/v1/passthrough/` is preserved verbatim as the upstream path. Generated clients must URL-encode any `/` within a single segment as `%2F` (e.g. `users%2Fme`), since an OpenAPI path parameter cannot contain a raw slash.", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "The action's system_id (from `/v1/available-actions`). Selects which connection-model definition resolves the upstream call. This is what the SDK's `triggerAction` sets.", "in": "header", "name": "X-One-Action-Id", "required": true, "schema": { "type": "string" } }, { "description": "The connection to run against. Required whichever credential you present: it selects the connection, it does not authenticate you, and a request without it is refused before the handler runs.", "in": "header", "name": "X-One-Connection-Key", "required": true, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the destination API. Sent as-is to the upstream platform with the request's content-type preserved.", "required": true }, "responses": { "200": { "description": "Response proxied back from the destination API" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "summary": "Passthrough request", "tags": [ "Passthrough" ] }, "head": { "description": "Forwards an arbitrary HTTP request to the upstream platform. The method, URL path, query parameters, and body are all preserved \u2014 credentials are resolved from your connection and signed in automatically. Use this when no first-class action exists for what you need to do on the platform.", "operationId": "passthrough", "parameters": [ { "description": "API path forwarded to the destination platform (e.g. `users/me`, `contacts`). Anything after `/v1/passthrough/` is preserved verbatim as the upstream path. Generated clients must URL-encode any `/` within a single segment as `%2F` (e.g. `users%2Fme`), since an OpenAPI path parameter cannot contain a raw slash.", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "The action's system_id (from `/v1/available-actions`). Selects which connection-model definition resolves the upstream call. This is what the SDK's `triggerAction` sets.", "in": "header", "name": "X-One-Action-Id", "required": true, "schema": { "type": "string" } }, { "description": "The connection to run against. Required whichever credential you present: it selects the connection, it does not authenticate you, and a request without it is refused before the handler runs.", "in": "header", "name": "X-One-Connection-Key", "required": true, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the destination API. Sent as-is to the upstream platform with the request's content-type preserved.", "required": true }, "responses": { "200": { "description": "Response proxied back from the destination API" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "summary": "Passthrough request", "tags": [ "Passthrough" ] }, "options": { "description": "Forwards an arbitrary HTTP request to the upstream platform. The method, URL path, query parameters, and body are all preserved \u2014 credentials are resolved from your connection and signed in automatically. Use this when no first-class action exists for what you need to do on the platform.", "operationId": "passthrough", "parameters": [ { "description": "API path forwarded to the destination platform (e.g. `users/me`, `contacts`). Anything after `/v1/passthrough/` is preserved verbatim as the upstream path. Generated clients must URL-encode any `/` within a single segment as `%2F` (e.g. `users%2Fme`), since an OpenAPI path parameter cannot contain a raw slash.", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "The action's system_id (from `/v1/available-actions`). Selects which connection-model definition resolves the upstream call. This is what the SDK's `triggerAction` sets.", "in": "header", "name": "X-One-Action-Id", "required": true, "schema": { "type": "string" } }, { "description": "The connection to run against. Required whichever credential you present: it selects the connection, it does not authenticate you, and a request without it is refused before the handler runs.", "in": "header", "name": "X-One-Connection-Key", "required": true, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the destination API. Sent as-is to the upstream platform with the request's content-type preserved.", "required": true }, "responses": { "200": { "description": "Response proxied back from the destination API" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "summary": "Passthrough request", "tags": [ "Passthrough" ] }, "patch": { "description": "Forwards an arbitrary HTTP request to the upstream platform. The method, URL path, query parameters, and body are all preserved \u2014 credentials are resolved from your connection and signed in automatically. Use this when no first-class action exists for what you need to do on the platform.", "operationId": "passthrough", "parameters": [ { "description": "API path forwarded to the destination platform (e.g. `users/me`, `contacts`). Anything after `/v1/passthrough/` is preserved verbatim as the upstream path. Generated clients must URL-encode any `/` within a single segment as `%2F` (e.g. `users%2Fme`), since an OpenAPI path parameter cannot contain a raw slash.", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "The action's system_id (from `/v1/available-actions`). Selects which connection-model definition resolves the upstream call. This is what the SDK's `triggerAction` sets.", "in": "header", "name": "X-One-Action-Id", "required": true, "schema": { "type": "string" } }, { "description": "The connection to run against. Required whichever credential you present: it selects the connection, it does not authenticate you, and a request without it is refused before the handler runs.", "in": "header", "name": "X-One-Connection-Key", "required": true, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the destination API. Sent as-is to the upstream platform with the request's content-type preserved.", "required": true }, "responses": { "200": { "description": "Response proxied back from the destination API" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "summary": "Passthrough request", "tags": [ "Passthrough" ] }, "post": { "description": "Forwards an arbitrary HTTP request to the upstream platform. The method, URL path, query parameters, and body are all preserved \u2014 credentials are resolved from your connection and signed in automatically. Use this when no first-class action exists for what you need to do on the platform.", "operationId": "passthrough", "parameters": [ { "description": "API path forwarded to the destination platform (e.g. `users/me`, `contacts`). Anything after `/v1/passthrough/` is preserved verbatim as the upstream path. Generated clients must URL-encode any `/` within a single segment as `%2F` (e.g. `users%2Fme`), since an OpenAPI path parameter cannot contain a raw slash.", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "The action's system_id (from `/v1/available-actions`). Selects which connection-model definition resolves the upstream call. This is what the SDK's `triggerAction` sets.", "in": "header", "name": "X-One-Action-Id", "required": true, "schema": { "type": "string" } }, { "description": "The connection to run against. Required whichever credential you present: it selects the connection, it does not authenticate you, and a request without it is refused before the handler runs.", "in": "header", "name": "X-One-Connection-Key", "required": true, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the destination API. Sent as-is to the upstream platform with the request's content-type preserved.", "required": true }, "responses": { "200": { "description": "Response proxied back from the destination API" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "summary": "Passthrough request", "tags": [ "Passthrough" ] }, "put": { "description": "Forwards an arbitrary HTTP request to the upstream platform. The method, URL path, query parameters, and body are all preserved \u2014 credentials are resolved from your connection and signed in automatically. Use this when no first-class action exists for what you need to do on the platform.", "operationId": "passthrough", "parameters": [ { "description": "API path forwarded to the destination platform (e.g. `users/me`, `contacts`). Anything after `/v1/passthrough/` is preserved verbatim as the upstream path. Generated clients must URL-encode any `/` within a single segment as `%2F` (e.g. `users%2Fme`), since an OpenAPI path parameter cannot contain a raw slash.", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "The action's system_id (from `/v1/available-actions`). Selects which connection-model definition resolves the upstream call. This is what the SDK's `triggerAction` sets.", "in": "header", "name": "X-One-Action-Id", "required": true, "schema": { "type": "string" } }, { "description": "The connection to run against. Required whichever credential you present: it selects the connection, it does not authenticate you, and a request without it is refused before the handler runs.", "in": "header", "name": "X-One-Connection-Key", "required": true, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "string" } } }, "description": "Payload forwarded to the destination API. Sent as-is to the upstream platform with the request's content-type preserved.", "required": true }, "responses": { "200": { "description": "Response proxied back from the destination API" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "summary": "Passthrough request", "tags": [ "Passthrough" ] } }, "/v1/users/flags": { "get": { "operationId": "get_user_flags", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFlags" } } }, "description": "User flags" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable entity" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "tags": [ "Users" ] } }, "/v1/users/whoami": { "get": { "description": "Returns the user that owns the calling secret key, along with the organization and project the key is scoped to (when applicable).", "operationId": "whoami", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoamiResponse" } } }, "description": "Identity of the caller" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unprocessable entity" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Whoami", "tags": [ "Whoami" ] } }, "/v1/vault/connections": { "get": { "description": "Returns the connections you have access to. The result is filtered to your scope automatically \u2014 your own connections, your organization's, or your project's, depending on the key you use. Filter further by platform, identity, key, or tags.", "operationId": "list_vault_connections", "parameters": [ { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Filter by the upstream platform identity (e.g. the user's email\nor remote account id) the connection authenticates as.", "in": "query", "name": "identity", "required": false, "schema": { "type": "string" } }, { "description": "Restrict the result to connections of the given identity type\n(`user`, `account`, `workspace`, etc.).", "in": "query", "name": "identityType", "required": false, "schema": { "$ref": "#/components/schemas/ConnectionIdentityType" } }, { "description": "Filter by platform identifier (e.g. `gmail`, `shopify`).", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "Filter by exact connection key. Accepts a single key or a\ncomma-separated list.", "in": "query", "name": "key", "required": false, "schema": { "type": "string" } }, { "description": "Filter by tags attached to the connection. Accepts a single tag\nor a comma-separated list.", "in": "query", "name": "tags", "required": false, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_VaultConnectionView" } } }, "description": "Paginated list of vault connections" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-One-Secret": [] }, { "OAuth2": [ "user:connections:read" ] }, { "OAuth2": [ "org:connections:read" ] }, { "OAuth2": [ "project:connections:read" ] } ], "summary": "List vault connections", "tags": [ "Vault" ] } }, "/v1/vault/connections/{id}": { "delete": { "description": "Permanently removes a connection and its stored credentials. Any future action or passthrough call using this connection will fail.", "operationId": "delete_vault_connection", "parameters": [ { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Vault connection deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "summary": "Delete vault connection", "tags": [ "Vault" ] }, "get": { "description": "Returns the details of a single connection. Scoped automatically to your credential \u2014 you'll only see connections you have access to.", "operationId": "retrieve_vault_connection", "parameters": [ { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultConnectionView" } } }, "description": "Vault connection details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:connections:read" ] }, { "OAuth2": [ "org:connections:read" ] }, { "OAuth2": [ "project:connections:read" ] } ], "summary": "Retrieve vault connection", "tags": [ "Vault" ] }, "patch": { "description": "Replaces the tags on a connection. The list you send becomes the new set \u2014 tags you omit are removed. Scoped automatically to your credential.", "operationId": "update_vault_connection_tags", "parameters": [ { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "tags": [ "production", "billing" ] }, "schema": { "$ref": "#/components/schemas/UpdateConnection" } } }, "required": true }, "responses": { "200": { "description": "Vault connection tags updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "user:connections:write" ] }, { "OAuth2": [ "org:connections:write" ] }, { "OAuth2": [ "project:connections:write" ] } ], "summary": "Update vault connection tags", "tags": [ "Vault" ] } }, "/v1/vault/organizations/{org_id}/connections": { "get": { "description": "Returns the connections inside an organization. Useful when an admin needs to see every connection across the org regardless of which project they're signed into. Filter by platform, identity, key, or tags.", "operationId": "list_organization_vault_connections", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Filter by the upstream platform identity (e.g. the user's email\nor remote account id) the connection authenticates as.", "in": "query", "name": "identity", "required": false, "schema": { "type": "string" } }, { "description": "Restrict the result to connections of the given identity type\n(`user`, `account`, `workspace`, etc.).", "in": "query", "name": "identityType", "required": false, "schema": { "$ref": "#/components/schemas/ConnectionIdentityType" } }, { "description": "Filter by platform identifier (e.g. `gmail`, `shopify`).", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "Filter by exact connection key. Accepts a single key or a\ncomma-separated list.", "in": "query", "name": "key", "required": false, "schema": { "type": "string" } }, { "description": "Filter by tags attached to the connection. Accepts a single tag\nor a comma-separated list.", "in": "query", "name": "tags", "required": false, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_VaultConnectionView" } } }, "description": "Paginated list of organization vault connections" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "org:connections:read" ] } ], "summary": "List organization vault connections", "tags": [ "Vault" ] } }, "/v1/vault/organizations/{org_id}/connections/{id}": { "get": { "description": "Returns the details of a single connection inside an organization, including its platform, identity, tags, and current status.", "operationId": "retrieve_organization_vault_connection", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Organization-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultConnectionView" } } }, "description": "Organization vault connection details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "org:connections:read" ] } ], "summary": "Retrieve organization vault connection", "tags": [ "Vault" ] } }, "/v1/vault/organizations/{org_id}/projects/{project_id}/connections": { "get": { "description": "Returns the connections inside a specific project. Useful when a caller with org-wide access needs to narrow to one project. Filter by platform, identity, key, or tags.", "operationId": "list_project_vault_connections", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "page", "required": true, "schema": { "$ref": "#/components/schemas/Page" } }, { "description": "Filter by the upstream platform identity (e.g. the user's email\nor remote account id) the connection authenticates as.", "in": "query", "name": "identity", "required": false, "schema": { "type": "string" } }, { "description": "Restrict the result to connections of the given identity type\n(`user`, `account`, `workspace`, etc.).", "in": "query", "name": "identityType", "required": false, "schema": { "$ref": "#/components/schemas/ConnectionIdentityType" } }, { "description": "Filter by platform identifier (e.g. `gmail`, `shopify`).", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "Filter by exact connection key. Accepts a single key or a\ncomma-separated list.", "in": "query", "name": "key", "required": false, "schema": { "type": "string" } }, { "description": "Filter by tags attached to the connection. Accepts a single tag\nor a comma-separated list.", "in": "query", "name": "tags", "required": false, "schema": { "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_VaultConnectionView" } } }, "description": "Paginated list of project vault connections" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "project:connections:read" ] } ], "summary": "List project vault connections", "tags": [ "Vault" ] } }, "/v1/vault/organizations/{org_id}/projects/{project_id}/connections/{id}": { "get": { "description": "Returns the details of a single connection inside a project.", "operationId": "retrieve_project_vault_connection", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Connection ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Selects the tenant this request acts in. Omit it to act in your personal scope.", "in": "header", "name": "X-One-Project-Id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultConnectionView" } } }, "description": "Project vault connection details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid connection credentials" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Connection not found" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream platform unavailable" } }, "security": [ { "X-Pica-Secret": [] }, { "OAuth2": [ "project:connections:read" ] } ], "summary": "Retrieve project vault connection", "tags": [ "Vault" ] } }, "/v1/webhooks/events/organizations/{org_id}": { "get": { "description": "Returns the recent webhook events emitted for an organization. Use this to see what happened and how each subscription handled it. Filter by event type or by a time range.", "operationId": "list_org_webhook_events", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Filter by webhook event type (e.g. `organization.created`,\n`subscription.test.completed`).", "in": "query", "name": "eventType", "required": false, "schema": { "type": "string" } }, { "description": "ISO-8601 timestamp \u2014 return only events emitted at or after this time.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "ISO-8601 timestamp \u2014 return only events emitted at or before this time.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_WebhookEventView" } } }, "description": "List of org webhook events" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List organization webhook events", "tags": [ "Webhook Events" ] } }, "/v1/webhooks/events/organizations/{org_id}/projects/{project_id}": { "get": { "description": "Returns the recent webhook events emitted for a project. Filter by event type or by a time range.", "operationId": "list_project_webhook_events", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Filter by webhook event type (e.g. `organization.created`,\n`subscription.test.completed`).", "in": "query", "name": "eventType", "required": false, "schema": { "type": "string" } }, { "description": "ISO-8601 timestamp \u2014 return only events emitted at or after this time.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "ISO-8601 timestamp \u2014 return only events emitted at or before this time.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_WebhookEventView" } } }, "description": "List of project webhook events" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List project webhook events", "tags": [ "Webhook Events" ] } }, "/v1/webhooks/relay": { "get": { "description": "Returns the webhook relay endpoints you have access to. Scoped automatically to your credential \u2014 you see your own personal endpoints, or org / project endpoints depending on the key you use.", "operationId": "list_relay_endpoints", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_WebhookRelayEndpointView" } } }, "description": "Paginated list of relay endpoints" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List relay endpoints", "tags": [ "Webhook Relay" ] }, "post": { "description": "Registers a new webhook relay endpoint against a connection. Choose which event types trigger deliveries and what actions should run when they fire (forward to a URL, run a passthrough call, etc.). The endpoint needs to be activated next before the upstream platform starts sending events.", "operationId": "create_relay_endpoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEndpointParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRelayEndpointView" } } }, "description": "Created relay endpoint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Create relay endpoint", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/config/{conn_def_id}": { "get": { "description": "Returns the dashboard-facing setup instructions for a connector's webhook relay \u2014 the required fields, step-by-step instructions, and the URL the user must paste into the upstream platform.", "operationId": "get_webhook_relay_config", "parameters": [ { "description": "Connection definition ID", "in": "path", "name": "conn_def_id", "required": true, "schema": { "$ref": "#/components/schemas/ConnectionDefinitionId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookFrontend" } } }, "description": "Webhook frontend config for the platform" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Get webhook relay setup config", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/event-types": { "get": { "description": "Returns the event types a given platform can deliver. Pair with the platform list to drive a picker UI.", "operationId": "list_webhook_relay_event_types", "parameters": [ { "description": "Platform identifier to enumerate event types for (e.g. `stripe`,\n`hubspot`).", "in": "query", "name": "platform", "required": true, "schema": { "type": "string" } }, { "description": "Free-text filter narrowing the returned event types.", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "type": "string" }, "type": "array" } } }, "description": "List of event types" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List webhook relay event types", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/events": { "get": { "description": "Returns inbound webhook events the relay has received. Each row is one delivery from an upstream platform. Filter by connection, platform, event type, or a time range.", "operationId": "list_relay_events", "parameters": [ { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Restrict to relay events received on the given connection.", "in": "query", "name": "connectionId", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Restrict to relay events for the given upstream platform (e.g. `stripe`,\n`hubspot`).", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "Restrict to relay events of the named upstream event type.", "in": "query", "name": "eventType", "required": false, "schema": { "type": "string" } }, { "description": "ISO-8601 timestamp \u2014 return only events received at or after this time.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "ISO-8601 timestamp \u2014 return only events received at or before this time.", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_WebhookRelayEventView" } } }, "description": "Paginated list of relay events" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List relay events", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/events/{id}": { "get": { "description": "Returns a single inbound webhook event, including the raw payload the upstream platform sent.", "operationId": "get_relay_event", "parameters": [ { "description": "Relay event ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRelayEventView" } } }, "description": "Relay event details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Get relay event", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/events/{id}/deliveries": { "get": { "description": "Returns every delivery attempt the relay made for an event \u2014 one row per matched endpoint per retry. Useful for debugging why an event did or did not reach a particular endpoint.", "operationId": "list_relay_event_deliveries", "parameters": [ { "description": "Relay event ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RelayDeliveryView" }, "type": "array" } } }, "description": "List of deliveries for the event" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List deliveries for a relay event", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/incoming/{platform}/{connection_key}": { "post": { "description": "Inbound endpoint upstream platforms POST to. The relay verifies the signature, persists the event, and forwards it to every matching endpoint. You do not call this yourself \u2014 it's the URL the upstream platform delivers to.", "operationId": "receive_webhook_relay", "parameters": [ { "description": "Platform identifier (e.g. stripe)", "in": "path", "name": "platform", "required": true, "schema": { "type": "string" } }, { "description": "Connection key the upstream platform is delivering for", "in": "path", "name": "connection_key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Raw webhook payload from the platform", "required": true }, "responses": { "200": { "description": "Webhook received and queued" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "summary": "Receive inbound webhook delivery", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/organizations/{org_id}/projects/{project_id}/{id}/activate": { "post": { "description": "Activates a project-scoped relay endpoint \u2014 registers its inbound URL with the upstream platform so events start flowing.", "operationId": "activate_project_relay_endpoint", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Relay endpoint ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateEndpointParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRelayEndpointView" } } }, "description": "Activated relay endpoint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Activate project relay endpoint", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/organizations/{org_id}/{id}/activate": { "post": { "description": "Activates an organization-scoped relay endpoint \u2014 registers its inbound URL with the upstream platform so events start flowing.", "operationId": "activate_organization_relay_endpoint", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Relay endpoint ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateEndpointParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRelayEndpointView" } } }, "description": "Activated relay endpoint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Activate organization relay endpoint", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/platforms": { "get": { "description": "Returns every platform you can receive inbound webhooks from via the relay. Each entry shows the platform name and how many distinct event types it can emit.", "operationId": "list_webhook_relay_platforms", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/WebhookRelayPlatformInfo" }, "type": "array" } } }, "description": "Platforms supporting webhook relay" } }, "summary": "List webhook relay platforms", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/{id}": { "delete": { "description": "Removes a relay endpoint. The relay also tries to deactivate the corresponding webhook on the upstream platform. No further deliveries will be queued, though events already in flight will still complete.", "operationId": "delete_relay_endpoint", "parameters": [ { "description": "Relay endpoint ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRelayEndpointView" } } }, "description": "Deleted relay endpoint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Delete relay endpoint", "tags": [ "Webhook Relay" ] }, "get": { "description": "Returns the configuration of a single relay endpoint \u2014 its connection, subscribed event types, actions, and active status.", "operationId": "get_relay_endpoint", "parameters": [ { "description": "Relay endpoint ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRelayEndpointView" } } }, "description": "Relay endpoint details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Get relay endpoint", "tags": [ "Webhook Relay" ] }, "patch": { "description": "Updates a relay endpoint. Pass only the fields you want to change. Changes apply to future deliveries; events already in flight are dispatched using the previous configuration.", "operationId": "update_relay_endpoint", "parameters": [ { "description": "Relay endpoint ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEndpointParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRelayEndpointView" } } }, "description": "Updated relay endpoint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Update relay endpoint", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/{id}/activate": { "post": { "description": "Registers the relay's inbound URL with the upstream platform so it starts sending events. Must be called once after creating an endpoint \u2014 without activation no events flow.", "operationId": "activate_relay_endpoint", "parameters": [ { "description": "Relay endpoint ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateEndpointParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRelayEndpointView" } } }, "description": "Activated relay endpoint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Activate relay endpoint", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/relay/{id}/deliveries": { "get": { "description": "Returns every delivery the relay attempted against an endpoint \u2014 one row per matched event per retry. Use this to see recent traffic and whether deliveries are succeeding or failing.", "operationId": "list_relay_endpoint_deliveries", "parameters": [ { "description": "Relay endpoint ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RelayDeliveryView" }, "type": "array" } } }, "description": "List of deliveries for the endpoint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication required" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List deliveries for a relay endpoint", "tags": [ "Webhook Relay" ] } }, "/v1/webhooks/subscriptions/by-key/{key}": { "put": { "description": "Registers a listener under a stable name you choose. Calling it again with the same name reconciles the existing listener instead of creating a second one, so it is safe to run on every application boot. A signing secret is required, because deliveries are only signed when the subscription has one.", "operationId": "upsert_webhook_subscription", "parameters": [ { "description": "Stable listener name, unique per account", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertSubscriptionParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } }, "description": "Created or reconciled webhook subscription" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Create or reconcile a webhook listener", "tags": [ "Webhook Subscriptions" ] } }, "/v1/webhooks/subscriptions/organizations/{org_id}": { "get": { "description": "Returns the webhook subscriptions registered for an organization.", "operationId": "list_org_webhook_subscriptions", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_WebhookSubscriptionView" } } }, "description": "List of org webhook subscriptions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List organization webhook subscriptions", "tags": [ "Webhook Subscriptions" ] }, "post": { "description": "Subscribes a URL to receive webhooks when events happen in an organization. Choose which event types you care about and optionally provide a signing secret so you can verify the payloads.", "operationId": "create_org_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } }, "description": "Created org webhook subscription" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Create organization webhook subscription", "tags": [ "Webhook Subscriptions" ] } }, "/v1/webhooks/subscriptions/organizations/{org_id}/projects/{project_id}": { "get": { "description": "Returns the webhook subscriptions registered in a project.", "operationId": "list_project_webhook_subscriptions", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Items per page. Default 20, hard-capped at 150. `limit=0` is\ntreated as 1. Larger values silently clamp.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int64", "maximum": 150, "minimum": 0, "type": "integer" } }, { "description": "Page number for pagination (1-indexed). Defaults to 1.", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Number of items to skip before the first returned item. Defaults to 0.\nMost callers should leave this at 0 and rely on `page` + `limit`.", "example": 0, "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated_WebhookSubscriptionView" } } }, "description": "List of project webhook subscriptions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "List project webhook subscriptions", "tags": [ "Webhook Subscriptions" ] }, "post": { "description": "Subscribes a URL to receive webhooks for events that happen inside a project. Project subscriptions only see events from this project \u2014 they do not fire on org-level activity.", "operationId": "create_project_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } }, "description": "Created project webhook subscription" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Create project webhook subscription", "tags": [ "Webhook Subscriptions" ] } }, "/v1/webhooks/subscriptions/organizations/{org_id}/projects/{project_id}/{id}": { "delete": { "description": "Permanently removes a project webhook subscription. To pause deliveries instead, update the subscription and set it to inactive.", "operationId": "delete_project_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Subscription ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } }, "description": "Deleted project webhook subscription" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Delete project webhook subscription", "tags": [ "Webhook Subscriptions" ] }, "get": { "description": "Returns the configuration of a specific project webhook subscription.", "operationId": "get_project_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Subscription ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } }, "description": "Project webhook subscription" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Get project webhook subscription", "tags": [ "Webhook Subscriptions" ] }, "patch": { "description": "Updates a project webhook subscription. Pass only the fields you want to change.", "operationId": "update_project_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Subscription ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } }, "description": "Updated project webhook subscription" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Update project webhook subscription", "tags": [ "Webhook Subscriptions" ] } }, "/v1/webhooks/subscriptions/organizations/{org_id}/projects/{project_id}/{id}/test": { "post": { "description": "Sends a synthetic test event to a project webhook subscription. Use this to verify your receiver is reachable and that signature validation works end-to-end.", "operationId": "test_project_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Project ID", "in": "path", "name": "project_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Subscription ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventView" } } }, "description": "Test project webhook event" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Test project webhook subscription", "tags": [ "Webhook Subscriptions" ] } }, "/v1/webhooks/subscriptions/organizations/{org_id}/{id}": { "delete": { "description": "Permanently removes an organization webhook subscription. No further events will be delivered to its URL. To pause deliveries instead, update the subscription and set it to inactive.", "operationId": "delete_org_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Subscription ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } }, "description": "Deleted org webhook subscription" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Delete organization webhook subscription", "tags": [ "Webhook Subscriptions" ] }, "get": { "description": "Returns the configuration of a specific organization webhook subscription, including its URL, subscribed event types, and active status.", "operationId": "get_org_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Subscription ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } }, "description": "Org webhook subscription" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Get organization webhook subscription", "tags": [ "Webhook Subscriptions" ] }, "patch": { "description": "Updates an organization webhook subscription. Pass only the fields you want to change. Set the subscription to inactive to stop deliveries without removing it.", "operationId": "update_org_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Subscription ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionParams" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } }, "description": "Updated org webhook subscription" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Update organization webhook subscription", "tags": [ "Webhook Subscriptions" ] } }, "/v1/webhooks/subscriptions/organizations/{org_id}/{id}/test": { "post": { "description": "Sends a synthetic test event to an organization webhook subscription. Use this to verify your receiver is reachable and that signature validation works without waiting for a real event.", "operationId": "test_org_webhook_subscription", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Subscription ID", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventView" } } }, "description": "Test org webhook event" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid request" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Quota exceeded \u2014 upgrade plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Resource not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Internal server error" } }, "security": [ { "X-Pica-Secret": [] } ], "summary": "Test organization webhook subscription", "tags": [ "Webhook Subscriptions" ] } } }, "tags": [ { "description": "Proxy requests to external APIs through configured connections", "name": "Passthrough" }, { "description": "Manage webhook relay endpoints, events, and deliveries", "name": "Webhook Relay" }, { "description": "Manage AI agents for automation and orchestration", "name": "AI Agents" }, { "description": "View cron run history for AI agents", "name": "AI Agent Cron Runs" }, { "description": "Manage AI skills with session or secret key authentication", "name": "AI Skills" }, { "description": "Manage AI agent runner pods", "name": "AI Runners" }, { "description": "Manage secrets for AI agent runner pods", "name": "AI Runner Secrets" }, { "description": "Agency-side templates that produce per-customer link invitations", "name": "Link Templates" }, { "description": "Agency-side lifecycle of customer link invitations: send, list, resend, revoke", "name": "Link Invitations" }, { "description": "The live customer link: status, API-key rotation, and the customer-facing connect flow", "name": "Link" }, { "description": "Manage connection access restrictions", "name": "Access" }, { "description": "Search and list available actions for platforms", "name": "Actions" }, { "description": "AuthKit initialization and token management", "name": "AuthKit" }, { "description": "Manage connections", "name": "Connections" }, { "description": "List and retrieve connection definitions", "name": "Connection Definitions" }, { "description": "List and retrieve connection OAuth definitions", "name": "Connection OAuth Definitions" }, { "description": "List available connectors", "name": "Connectors" }, { "description": "Search knowledge base", "name": "Knowledge" }, { "description": "Programmatically manage organizations, their members, invitations, AuthKit configuration, and API keys with a service-account API key", "name": "Organizations" }, { "description": "Programmatically manage projects inside an organization \u2014 including members, invitations, and project-scoped API keys \u2014 with a service-account API key", "name": "Projects" }, { "description": "User management", "name": "Users" }, { "description": "Manage vault connections with detailed views", "name": "Vault" }, { "description": "Manage webhook subscriptions and events", "name": "Webhook Subscriptions" }, { "description": "Identify the caller behind a secret key", "name": "Whoami" } ] }