openapi: 3.1.0 info: version: "2026-04-01" title: Glean Platform API x-source-commit-sha: 5353ee55255d0b005a7a0230a8c4269867fc0593 x-open-api-commit-sha: 17965285e0c925e7777114af63271d165b2a7e99 servers: - url: https://{instance}-be.glean.com variables: instance: default: instance-name description: The instance name (typically the email domain without the TLD) that determines the deployment backend. security: - APIToken: [] paths: /api/agents/search: post: tags: - Agents summary: Search agents description: | Search agents available to the authenticated user by agent name. operationId: platform-agents-search x-glean-scopes: legacy: - AGENTS platform: - agents:read x-visibility: Public x-codegen-request-body-name: payload requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformAgentsSearchRequest" responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformAgentsSearchResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: agents x-speakeasy-name-override: search /api/agents/{agent_id}: get: tags: - Agents summary: Get agent description: | Retrieve details for an agent available to the authenticated user. operationId: platform-agents-get x-glean-scopes: legacy: - AGENTS platform: - agents:read x-visibility: Public parameters: - in: path name: agent_id description: ID of the agent to retrieve. required: true example: "{agent_id}" schema: type: string minLength: 1 responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformAgentGetResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: agents x-speakeasy-name-override: get /api/agents/{agent_id}/schemas: get: tags: - Agents summary: Get agent schemas description: | Retrieve an agent's input and output JSON schemas. operationId: platform-agents-get-schemas x-glean-scopes: legacy: - AGENTS platform: - agents:read x-visibility: Public parameters: - in: path name: agent_id description: ID of the agent whose schemas should be retrieved. required: true example: "{agent_id}" schema: type: string minLength: 1 - in: query name: include_tools description: Whether to include tool metadata in the response. required: false schema: type: boolean default: false responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformAgentSchemasResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: agents x-speakeasy-name-override: getSchemas /api/agents/{agent_id}/runs: post: tags: - Agents summary: Create agent run description: | Execute an agent run. By default, set `stream` to true to receive server-sent events; otherwise the response contains the final agent messages. Set `execution_mode` to `DURABLE` to persist a new run and return its initial snapshot with HTTP 201 without waiting for execution. Poll the agent-scoped GET run endpoint for progress. Durable execution continues after an HTTP disconnect, but is not automatically resumed after a QE restart or crash. An active turn becomes overdue more than 40 minutes after acceptance (a 30-minute execution timeout plus 10 minutes of grace). The next GET of the run marks the overdue turn FAILED without replay; there is no periodic sweep. Without a GET, the stored run can remain RUNNING. Failure does not prove that external tool work has stopped. Paused runs are not expired; an accepted approval continuation starts a fresh deadline. Each POST creates a new run; retrying a POST can create another execution. Submit pending approval decisions through the run responses endpoint, and cancellation can be requested through the run cancellations endpoint. A run tracks one workflow execution; automatic background-subagent wake turns are separate executions, not continuations tracked by this run ID. operationId: platform-agents-create-run x-glean-scopes: legacy: - AGENTS platform: - agents:run x-visibility: Public x-codegen-request-body-name: payload parameters: - in: path name: agent_id description: ID of the agent to run. required: true example: "{agent_id}" schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformAgentRunCreateRequest" responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformAgentRunWaitResponse" text/event-stream: schema: type: string description: | Server-sent events emitted by the running agent. Successful runs emit `message` events. A terminal failure after the stream has started emits exactly one `run.failed` event whose `data` is an `AgentRunFailedEventData` payload, then closes. example: | id: 1 event: message data: {"messages":[{"role":"GLEAN_AI","content":[{"text":"Hello","type":"text"}]}]} id: 2 event: message data: {"messages":[{"role":"GLEAN_AI","content":[{"text":", I can help with HR policy questions.","type":"text"}]}]} id: 3 event: run.failed data: {"error":{"type":"https://developers.glean.com/errors/spend-limit-exceeded","title":"Spend Limit Exceeded","status":403,"detail":"You've reached the monthly limit set by your admin.","code":"spend_limit_exceeded","request_id":"req_123","documentation_url":"https://developers.glean.com/errors/spend-limit-exceeded"}} "201": description: | Durable run persisted and started. The snapshot is immediately retrievable through GET /api/agents/{agent_id}/runs/{run_id}. Execution failures appear in the run state. content: application/json: schema: $ref: "#/components/schemas/PlatformAgentRunResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "409": $ref: "#/components/responses/PlatformConflict" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "422": description: Returned when the agent has tools the caller must authorize before the run can start. `authentication_suggestions` names each such tool; POST its `server_id` to the Client API's `/tool-servers/{serverId}/auth` with `returnUrl` in the request body to obtain an `authorizationUrl` to redirect the end user to, then retry the run once OAuth completes. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformUnauthorizedAgentToolsProblem" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: agents x-speakeasy-name-override: createRun /api/agents/{agent_id}/runs/{run_id}: get: tags: - Agents summary: Get agent run description: | Retrieve a persisted workflow execution owned by the authenticated user. The run must belong to the specified agent, and the user must still have access to that agent. Unknown runs, runs owned by another user, and mismatched agent/run identifiers return 404. Requires the agents.run scope. Executions without a persisted workflow record are not available through this endpoint. operationId: platform-agents-get-run x-glean-scopes: legacy: - AGENTS platform: - agents:run x-visibility: Public parameters: - in: path name: agent_id description: ID of the agent that owns the run. required: true example: "{agent_id}" schema: type: string minLength: 1 maxLength: 256 - in: path name: run_id description: ID of the durable run to retrieve. required: true example: "{run_id}" schema: type: string minLength: 1 maxLength: 256 responses: "200": description: Current persisted run snapshot. A failed execution is still a successful retrieval. content: application/json: schema: $ref: "#/components/schemas/PlatformAgentRunResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: agents x-speakeasy-name-override: getRun /api/agents/{agent_id}/cancellations: post: tags: - Agents summary: Cancel an agent run description: | Request cooperative cancellation of the durable agent run identified by `run_id` in the JSON body. Requires ownership, current agent access, and the agents.run scope. Sending a cancellation signal does not itself change an active run from RUNNING; poll GET run for the final state. Paused runs become CANCELLED without resuming execution. Repeated requests and requests for terminal runs return the current snapshot. Completion may win a race with cancellation. Completed tool side effects cannot be undone, and external work may continue if a tool does not support cancellation. Cancellation targets this run, not separate background-subagent executions. An active run without a cancellation registration returns 409. Cancellation signaling requires Redis. An interrupted active run can instead become FAILED through deadline cleanup; this does not verify that external tool work has stopped. operationId: platform-agents-cancel-run x-glean-scopes: legacy: - AGENTS platform: - agents:run x-visibility: Public x-codegen-request-body-name: payload parameters: - in: path name: agent_id description: ID of the agent that owns the run. required: true example: "{agent_id}" schema: type: string minLength: 1 maxLength: 256 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformAgentRunCancellationRequest" responses: "200": description: Current run snapshot after requesting cancellation, or an unchanged terminal run. content: application/json: schema: $ref: "#/components/schemas/PlatformAgentRunResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "409": $ref: "#/components/responses/PlatformConflict" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: agents x-speakeasy-name-override: cancelRun /api/agents/{agent_id}/responses: post: tags: - Agents summary: Respond to agent run approvals description: | Submit decisions for every pending tool approval in the paused run's current batch. The run is identified by `run_id` in the JSON body. Decisions apply only to the stored invocations and arguments; argument edits, authentication responses, and session-wide grants are not supported. The caller must own the run, still have agent access, and have the agents.run scope. Acceptance persists the decisions before resuming the same run and chat session. Identical accepted decisions return the current snapshot without another continuation. Conflicting, stale, incomplete, or non-pending decisions return 409. Cancellation registration failure returns 503 without accepting the decisions; retry the same approval batch. This retry guarantee does not cover an indeterminate database commit outcome. Go workflow approval resumes currently support one tool invocation and one approval response. Unsupported multi-tool or multi-decision Go resumes fail without executing tools. The resumed action must resolve to the tool identified by the stored approval request and paused checkpoint. Missing or inconsistent identity fails without executing tools. Execution continues after HTTP disconnects, but is not automatically resumed after a QE crash. Each accepted continuation starts a fresh 30-minute execution timeout and 40-minute cleanup deadline. Identical retries do not extend that deadline. Waiting for approval does not expire a run. The next GET marks an overdue active turn FAILED without replaying execution. operationId: platform-agents-create-run-responses x-glean-scopes: legacy: - AGENTS platform: - agents:run x-visibility: Public parameters: - in: path name: agent_id description: ID of the agent that owns the run. required: true example: "{agent_id}" schema: type: string minLength: 1 maxLength: 256 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformAgentRunResponsesRequest" responses: "200": description: Decisions accepted, or an identical retry. Poll GET run for continued execution. content: application/json: schema: $ref: "#/components/schemas/PlatformAgentRunResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "409": $ref: "#/components/responses/PlatformConflict" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: agents x-speakeasy-name-override: respondToRun /api/chat: post: tags: - Chat summary: Create a chat response description: | Run an assistant turn. The default response is JSON. HTTP clients request server-sent events by setting `stream` to true in the JSON body. An `Accept: text/event-stream` header does not replace `stream`. operationId: platform-chat-create x-glean-scopes: legacy: - CHAT platform: - chat:write x-visibility: Public x-codegen-request-body-name: payload requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/PlatformChatCreateRequest" - type: object required: - stream properties: stream: type: boolean const: false default: false responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformChatCompletedResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "422": $ref: "#/components/responses/PlatformUnprocessableEntity" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: chat x-speakeasy-name-override: create /api/skills: post: tags: - Skills summary: Create skill description: | Create a skill from an uploaded SKILL.md, .zip, or .skill bundle. If the authenticated user already has a skill with the same name, the existing skill is superseded with a new version, unless it is source-managed: a same-name create over a GitHub-imported skill returns 409, and the caller syncs the existing skill instead. Two concurrent same-name creates can still produce two skills. operationId: platform-skills-create x-glean-scopes: legacy: - SKILLS platform: - skills:write x-visibility: Public requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/PlatformSkillCreateRequest" x-codegen-request-body-name: request responses: "201": description: Skill created. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillCreateResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "409": $ref: "#/components/responses/PlatformConflict" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: create get: tags: - Skills summary: List skills description: | List every custom skill the authenticated caller can access. Built-in skills are excluded: they have no versions, content download, update, or delete, so their identifiers would fail most skill operations. Chat-authored skills shared with the caller without a listed grant are omitted: they stay retrievable by identifier when it is known, but this list does not discover them. operationId: platform-skills-list x-glean-scopes: legacy: - SKILLS platform: - skills:read x-visibility: Public parameters: - in: query name: page_size description: Maximum number of skills to return. Defaults to 20. Maximum is 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 20 - in: query name: cursor description: Opaque pagination cursor from a previous response. required: false schema: type: string minLength: 1 responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillsListResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: list /api/skills/import: post: tags: - Skills summary: Import skills from GitHub description: | Import one or more skills selected from a GitHub source preview. Each source URL is fetched and persisted as an independent skill with source provenance. This operation does not create a durable source resource. The import is atomic: if any source cannot be fetched, validated, or persisted, no skills are created. operationId: platform-skills-import x-glean-scopes: legacy: - SKILLS platform: - skills:write x-visibility: Public x-codegen-request-body-name: request requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformSkillImportRequest" responses: "201": description: Skills imported successfully. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillImportResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "408": $ref: "#/components/responses/PlatformRequestTimeout" "409": $ref: "#/components/responses/PlatformConflict" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "422": description: Returned when GitHub authorization is missing for a source URL. `authentication_suggestions` names the GitHub action pack to authorize; POST its `server_id` to the Client API's `/tool-servers/{serverId}/auth` with `returnUrl` in the request body to obtain an `authorizationUrl` to redirect the end user to, then retry the import once OAuth completes. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformUnauthorizedAgentToolsProblem" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: import /api/skills/validation: post: tags: - Skills summary: Validate skill bundle description: | Validate a skill bundle without persisting it. Accepts a SKILL.md, .zip, or .skill upload and returns parsed metadata plus the normalized file layout. operationId: platform-skills-validate x-glean-scopes: legacy: - SKILLS platform: - skills:write x-visibility: Public requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/PlatformSkillValidationRequest" x-codegen-request-body-name: request responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillValidationResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: validate /api/skills/sources/preview: post: tags: - Skills summary: Preview a GitHub skill source description: | Inspect a GitHub URL without persisting a source or any discovered skills. Set stream to true to receive repository scan progress as server-sent events; otherwise the response contains the completed preview. operationId: platform-skills-preview-source x-glean-scopes: legacy: - SKILLS platform: - skills:write x-visibility: Public x-codegen-request-body-name: request requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/PlatformSkillSourcePreviewRequest" - type: object required: - stream properties: stream: type: boolean const: false default: false responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillSourcePreviewResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "422": description: Returned when GitHub authorization is missing for the source URL. `authentication_suggestions` names the GitHub action pack to authorize; POST its `server_id` to the Client API's `/tool-servers/{serverId}/auth` with `returnUrl` in the request body to obtain an `authorizationUrl` to redirect the end user to, then retry the preview once OAuth completes. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformUnauthorizedAgentToolsProblem" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: previewSource /api/skills/{skill_id}: patch: tags: - Skills summary: Update skill description: | Enable or disable the skill for the authenticated caller without changing its content. The owner's update sets the skill's stored status. Any other caller's update applies only to that caller. operationId: platform-skills-update x-glean-scopes: legacy: - SKILLS platform: - skills:write x-visibility: Public parameters: - name: skill_id in: path required: true description: Glean skill ID. example: "{skill_id}" schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformSkillUpdateRequest" x-codegen-request-body-name: request responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillUpdateResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "409": $ref: "#/components/responses/PlatformConflict" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: update delete: tags: - Skills summary: Delete skill description: | Delete a skill the authenticated caller is allowed to manage. This operation permanently removes all versions of the skill. operationId: platform-skills-delete x-glean-scopes: legacy: - SKILLS platform: - skills:write x-visibility: Public parameters: - name: skill_id in: path required: true description: Glean skill ID. example: "{skill_id}" schema: type: string minLength: 1 responses: "204": description: Skill deleted. No content. "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: delete get: tags: - Skills summary: Retrieve skill description: | Retrieve metadata for a skill available to the authenticated user. operationId: platform-skills-get x-glean-scopes: legacy: - SKILLS platform: - skills:read x-visibility: Public parameters: - name: skill_id in: path required: true description: Glean skill ID. example: "{skill_id}" schema: type: string minLength: 1 responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillGetResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: retrieve /api/skills/{skill_id}/content: get: tags: - Skills summary: Download skill content description: | Download the latest installable bundle for a skill available to the authenticated user. operationId: platform-skills-get-content x-glean-scopes: legacy: - SKILLS platform: - skills:read x-visibility: Public parameters: - name: skill_id in: path required: true description: Glean skill ID. example: "{skill_id}" schema: type: string minLength: 1 responses: "200": description: Successful response. headers: Content-Disposition: description: Attachment filename for the skill bundle. schema: type: string content: application/octet-stream: schema: type: string format: binary "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: retrieveContent /api/skills/{skill_id}/sync: post: tags: - Skills summary: Sync a GitHub-imported skill description: | Refresh one GitHub-imported skill from its stored source URL. If the skill content has changed, this operation creates a new skill version. If the skill is no longer present upstream, the stored skill is left unchanged and must be deleted explicitly. operationId: platform-skills-sync x-glean-scopes: legacy: - SKILLS platform: - skills:write x-visibility: Public parameters: - name: skill_id in: path required: true description: ID of the GitHub-imported skill to sync. example: "{skill_id}" schema: type: string minLength: 1 responses: "200": description: Skill sync completed successfully. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillSyncResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "409": $ref: "#/components/responses/PlatformConflict" "422": description: Returned when GitHub authorization is missing for the stored source URL. `authentication_suggestions` names the GitHub action pack to authorize; POST its `server_id` to the Client API's `/tool-servers/{serverId}/auth` with `returnUrl` in the request body to obtain an `authorizationUrl` to redirect the end user to, then retry the sync once OAuth completes. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformUnauthorizedAgentToolsProblem" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: sync /api/skills/{skill_id}/versions: post: tags: - Skills summary: Create skill version description: | Create a new immutable version for an existing caller-managed skill from an uploaded SKILL.md, .zip, or .skill bundle. A create-version over a GitHub-imported skill returns 409, and the caller syncs the existing skill instead. operationId: platform-skills-create-version x-glean-scopes: legacy: - SKILLS platform: - skills:write x-visibility: Public parameters: - name: skill_id in: path required: true description: Glean skill ID. example: "{skill_id}" schema: type: string minLength: 1 requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/PlatformSkillVersionCreateRequest" x-codegen-request-body-name: request responses: "201": description: Skill version created. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillVersionCreateResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "409": $ref: "#/components/responses/PlatformConflict" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: createVersion get: tags: - Skills summary: List skill versions description: | List versions for a skill available to the authenticated user. operationId: platform-skills-list-versions x-glean-scopes: legacy: - SKILLS platform: - skills:read x-visibility: Public parameters: - name: skill_id in: path required: true description: Glean skill ID. example: "{skill_id}" schema: type: string minLength: 1 - in: query name: page_size description: Maximum number of versions to return. Defaults to 20. Maximum is 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 20 - in: query name: cursor description: Opaque pagination cursor from a previous response. required: false schema: type: string minLength: 1 responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillVersionsListResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: listVersions /api/skills/{skill_id}/versions/{version}: get: tags: - Skills summary: Retrieve skill version description: | Retrieve metadata for a skill version available to the authenticated user. operationId: platform-skills-get-version x-glean-scopes: legacy: - SKILLS platform: - skills:read x-visibility: Public parameters: - name: skill_id in: path required: true description: Glean skill ID. example: "{skill_id}" schema: type: string minLength: 1 - name: version in: path required: true description: Major version number. example: 1 schema: type: integer minimum: 1 responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformSkillVersionGetResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: retrieveVersion /api/skills/{skill_id}/versions/{version}/content: get: tags: - Skills summary: Download skill version content description: | Download the installable bundle for a skill version available to the authenticated user. operationId: platform-skills-get-version-content x-glean-scopes: legacy: - SKILLS platform: - skills:read x-visibility: Public parameters: - name: skill_id in: path required: true description: Glean skill ID. example: "{skill_id}" schema: type: string minLength: 1 - name: version in: path required: true description: Major version number. example: 1 schema: type: integer minimum: 1 responses: "200": description: Successful response. headers: Content-Disposition: description: Attachment filename for the skill bundle. schema: type: string content: application/octet-stream: schema: type: string format: binary "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: retrieveVersionContent /api/search: post: tags: - Search summary: Search description: | Search your organization's connected content and return ranked document results with cursor pagination. Use `GET /api/search/filters` to discover datasource identifiers and common filter fields. Built-in filter names are validated; other field names are accepted as custom filters and behavior depends on your Glean configuration and connected sources. Errors: HTTP 422 `unprocessable_query` returns no `results` or `next_cursor`. See `warnings` on the response for non-blocking issues such as partially available results. Not every query issue produces a warning or error. operationId: platform-search x-glean-scopes: legacy: - SEARCH platform: - search:query x-visibility: Public x-codegen-request-body-name: payload requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformSearchRequest" responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformSearchResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "422": $ref: "#/components/responses/PlatformUnprocessableEntity" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: search x-speakeasy-name-override: query /api/search/filters: get: tags: - Search summary: List search filters description: | List datasources and common built-in filter fields visible to the authenticated user. This is a best-effort catalog, not an exhaustive list of every filter search accepts. Without `query`, returns field metadata only and does not run a search. With a nonblank `query`, provide exactly one `datasources` value to request suggested filter values for that query; no documents are returned and this endpoint does not include warning objects. See `FilterFieldInfo.values` for limitations on suggested values. Rate-limited requests return HTTP 429 with `Retry-After`; temporary backend unavailability returns HTTP 503. operationId: platform-search-filters x-glean-scopes: legacy: - SEARCH platform: - search:query x-visibility: Public parameters: - in: query name: datasources description: | Restrict metadata to one or more datasource identifiers as returned by this endpoint (for example, `jira`). With a nonblank `query`, exactly one datasource is required. Unknown or inaccessible identifiers return `invalid_datasource`. required: false schema: type: array minItems: 1 items: type: string minLength: 1 - in: query name: query description: | Optional search query that requests suggested filter values for the selected datasource. Must be nonblank when present. Triggers a search for facet values only; does not return documents. required: false schema: type: string minLength: 1 responses: "200": description: Successful response. headers: Cache-Control: description: | Present as `no-store` for query-backed discovery responses. Catalog-only responses omit this endpoint-specific override. schema: type: string example: no-store content: application/json: schema: $ref: "#/components/schemas/PlatformSearchFiltersResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: search x-speakeasy-name-override: listFilters /api/admin/usage/settings: get: tags: - Usage summary: Get usage settings description: | Retrieve workspace-wide policy from the same configuration used by Billing. Group resolution uses the configured policy and its backend defaults; business justification is currently optional. No per-user settings are read, and updated_at is omitted because no policy-update timestamp is available. Requires admin.usage.settings:read and permission to read workspace billing; a global administrator role is not required. operationId: platform-admin-usage-settings-get x-visibility: Public x-glean-scopes: legacy: - ADMIN_USAGE platform: - admin.usage.settings:read x-glean-experimental: id: 8f4c2d6e-3b7a-4e1f-9c8d-5a2b6e4f7c9a introduced: "2026-09-14" responses: "200": description: Usage settings. content: application/json: schema: $ref: "#/components/schemas/PlatformUsageSettingsResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.usage x-speakeasy-name-override: getSettings patch: tags: - Usage summary: Update usage settings description: | Assign workspace-wide usage policy. Assignment is currently unavailable until a writer to authoritative Billing configuration is integrated. The backend config platform.usageSettingsWritesEnabled is disabled by default; enabling it alone does not implement assignment, and an authorized request still returns 503 without changing configuration or persisting a second copy of policy. Requires admin.usage.settings:write and permission to edit workspace billing; a global administrator role is not required. operationId: platform-admin-usage-settings-update x-visibility: Public x-glean-scopes: legacy: - ADMIN_USAGE platform: - admin.usage.settings:write x-glean-experimental: id: 443aeb3c-fdee-4da8-a756-37fa13922830 introduced: "2026-09-14" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformUsageSettingsUpdateRequest" example: multiple_membership_resolution: per_member: idp_groups: HIGHEST limit_increase_requests: business_justification: REQUIRED responses: "200": description: Updated usage settings. content: application/json: schema: $ref: "#/components/schemas/PlatformUsageSettingsResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.usage x-speakeasy-name-override: updateSettings /api/admin/usage/limits: get: tags: - Usage summary: List usage limits description: | List configured limits across Glean and external spend clients, plus aggregate agent limits. Organization and user limits identify their spend client; aggregate agent limits omit client_id. USER targets return the canonical user_id and, when available, the user's directory email. Requires admin.usage.limits:read and permission to read workspace billing. Optional filters match configured limits. Pages contain up to page_size matching results; the service continues scanning until the page is full or the collection is exhausted. Continue with next_cursor while has_more is true, keeping the same filters on every continuation request. The undeclared client_id and target_type query parameters are rejected; use the canonical filters parameter instead. operationId: platform-admin-usage-limits-list x-visibility: Public x-glean-scopes: legacy: - ADMIN_USAGE platform: - admin.usage.limits:read x-glean-experimental: id: ca19b3e8-9a6d-4a31-8f2f-6c7d8e9f0011 introduced: "2026-09-16" parameters: - name: page_size in: query description: Maximum number of limits to return. Defaults to 20; the maximum allowed is 100. example: 20 schema: type: integer minimum: 1 maximum: 100 default: 20 - name: cursor in: query description: Opaque cursor from a previous list response; resend the same filters when continuing. example: "{cursor}" schema: type: string - name: filters in: query description: | JSON-encoded array of filters. Supported fields are client_id and target_type; only EQUALS is supported and is the default operator. Values within a filter are OR'd; filters are AND'd, including repeated fields. Client IDs are opaque, case-sensitive strings, matched exactly without trimming; whitespace-only values are invalid. Client filters include organization, default-user, and user policies, but exclude aggregate agent policies without a client_id. target_type values are ORGANIZATION, DEFAULT_USER, USER, DEFAULT_AGENT, and AGENT. URL-encode the JSON array as one filters query value. content: application/json: schema: type: array items: type: object additionalProperties: false description: One equality filter on configured usage limits. required: - field - values properties: field: type: string description: Field to match; client_id or target_type. values: type: array minItems: 1 description: Nonblank values to match exactly; any value may match. items: type: string minLength: 1 operator: allOf: - $ref: "#/components/schemas/PlatformFilterOperator" default: EQUALS description: Comparison operator; only EQUALS is supported. example: - field: client_id values: - glean - field: target_type values: - ORGANIZATION - USER operator: EQUALS responses: "200": description: List of usage limits. content: application/json: schema: $ref: "#/components/schemas/PlatformListUsageLimitsResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.usage x-speakeasy-name-override: listLimits post: tags: - Usage summary: Upsert a usage limit description: | Create or replace a single usage limit by its natural key. Always returns 200 with the normalized limit. A USER target may be identified by user_id or email; an unknown user returns 404. Requires admin.usage.limits:write and permission to edit workspace billing. Personal usage grants do not allow limit changes. operationId: platform-admin-usage-limits-upsert x-visibility: Public x-glean-scopes: legacy: - ADMIN_USAGE platform: - admin.usage.limits:write requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformUsageLimit" example: target: type: ORGANIZATION usage_selector: client_id: glean period: type: RECURRING_CALENDAR_MONTH allocation_mode: SHARED_POOL value: mode: FINITE amount: "1000.00" unit: USD enforcement: HARD responses: "200": description: The upserted usage limit. content: application/json: schema: $ref: "#/components/schemas/PlatformUpsertUsageLimitResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.usage x-speakeasy-name-override: upsertLimit /api/admin/usage/limits/reset: post: tags: - Usage summary: Reset a usage limit description: | Remove a configured usage limit matching the selector without clearing measured usage. A USER target may be identified by user_id or email, including a user no longer in the directory. Requires admin.usage.limits:write and permission to edit workspace billing. operationId: platform-admin-usage-limits-reset x-visibility: Public x-glean-scopes: legacy: - ADMIN_USAGE platform: - admin.usage.limits:write x-glean-experimental: id: ca19b3e8-9a6d-4a31-8f2f-6c7d8e9f0013 introduced: "2026-09-16" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformUsageLimitKey" example: target: type: USER email: user@example.com usage_selector: client_id: glean period: type: RECURRING_CALENDAR_MONTH responses: "200": description: Reset result. content: application/json: schema: $ref: "#/components/schemas/PlatformResetUsageLimitsResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.usage x-speakeasy-name-override: resetLimit /api/admin/usage/limits/batch: post: tags: - Usage summary: Apply usage limit policies description: | Apply one or more usage limit policy changes atomically. This action sets policy by natural key; it does not create addressable resources or return resource locations. Every change succeeds or none are applied. USER targets may be identified by user_id or email; each resolves to the canonical user_id before duplicate natural keys are checked. Requires admin.usage.limits:write and permission to edit workspace billing. operationId: platform-admin-usage-limits-batch x-visibility: Public x-glean-scopes: legacy: - ADMIN_USAGE platform: - admin.usage.limits:write x-glean-experimental: id: ca19b3e8-9a6d-4a31-8f2f-6c7d8e9f0014 introduced: "2026-09-16" requestBody: required: true content: application/json: schema: type: array description: Usage limit policies to apply atomically. minItems: 1 maxItems: 100 items: $ref: "#/components/schemas/PlatformUsageLimit" example: - target: type: ORGANIZATION usage_selector: client_id: glean period: type: RECURRING_CALENDAR_MONTH allocation_mode: SHARED_POOL value: mode: FINITE amount: "1000.00" unit: USD enforcement: HARD - target: type: USER email: user@example.com usage_selector: client_id: glean period: type: RECURRING_CALENDAR_MONTH value: mode: FINITE amount: "50.00" unit: USD enforcement: HARD responses: "200": description: The applied usage limit policies. content: application/json: schema: $ref: "#/components/schemas/PlatformBatchUsageLimitsResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.usage x-speakeasy-name-override: applyLimits /api/admin/usage/limits/evaluate: post: tags: - Usage summary: Evaluate administrative usage limit headroom description: | Evaluate the effective usage limits for a selector and return the current decision (AVAILABLE, WARNING, or BLOCKED) based on accrued usage. Requires admin.usage:evaluate and permission to read workspace billing, not a global administrator role. An explicit usage_selector.client_id selects the Glean or external spend client; it is never inferred from the caller. Returns all applicable limit values and counters, with effective headroom separated by unit. Agent counters retain aggregate scope. Billing readers receive exact IdP-group source identities. A USER target may be identified by user_id or email. Evaluation reports configured-budget status even when runtime enforcement switches are off; it does not perform request admission, model eligibility, or agent-run preflight checks. operationId: platform-admin-usage-limits-evaluate x-visibility: Public x-glean-scopes: legacy: - ADMIN_USAGE platform: - admin.usage:evaluate x-glean-experimental: id: 70bc17be-ccdb-4e9e-b1e7-1a75256c6ee1 introduced: "2026-09-18" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformEvaluateUsageLimitRequest" example: target: type: USER email: user@example.com usage_selector: client_id: glean period: type: RECURRING_CALENDAR_MONTH responses: "200": description: Evaluation result. content: application/json: schema: $ref: "#/components/schemas/PlatformEvaluateUsageLimitResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.usage x-speakeasy-name-override: evaluateUsage /api/usage/limits/evaluate: post: tags: - Usage summary: Evaluate usage limit headroom description: | Evaluate the effective usage limits for a selector and return the current decision (AVAILABLE, WARNING, or BLOCKED) based on accrued usage. Requires usage:evaluate, without workspace billing permission. Omit target to evaluate the authenticated canonical user. An explicit USER must identify that user by canonical ID, known alias ID, email, or known alias email; every supplied field must identify the caller. An explicit AGENT requires current owner/editor or applicable global agent-edit permission; disabled agents remain eligible. Subagents, other users, ORGANIZATION, and default targets are forbidden on this route, even for billing administrators. Missing, inaccessible, and subagent targets return the same 403 insufficient_permissions. An explicit usage_selector.client_id selects the Glean or external spend client; it is never inferred from the caller. Agent evaluation reports aggregate agent usage and the selected client's organization limit, not the caller's personal slice or a complete run preflight. All applicable limit values, used counters, decisions, and headroom are returned; USD and credits have separate effective_limits. IdP-group source identities require billing-read permission. Other callers receive an IDP_GROUP source with is_identity_restricted true and no group_id, without suppressing the policy's value, counter, or decision. Evaluation reports configured-budget status even when runtime enforcement switches are off; it does not perform request admission, model eligibility, or agent-run preflight checks. operationId: platform-usage-limits-evaluate x-visibility: Public x-glean-scopes: legacy: - USAGE platform: - usage:evaluate x-glean-experimental: id: ca19b3e8-9a6d-4a31-8f2f-6c7d8e9f0015 introduced: "2026-09-16" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformEvaluateCallerUsageLimitRequest" example: usage_selector: client_id: glean period: type: RECURRING_CALENDAR_MONTH responses: "200": description: Evaluation result. content: application/json: schema: $ref: "#/components/schemas/PlatformEvaluateUsageLimitResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: usage x-speakeasy-name-override: evaluateUsage /api/usage/limit-increase-requests: post: tags: - Usage summary: Submit a personal limit-increase request operationId: platform-usage-requests-create x-glean-scopes: legacy: - USAGE_LIMIT_INCREASE_REQUESTS platform: - usage.limit_increase_requests:write x-visibility: Public x-glean-experimental: id: d9f125f8-85f3-4221-8627-0b39f6d5b4ab introduced: "2026-09-25" description: | Requires usage.limit_increase_requests:write. The target is the authenticated canonical user, and requester identity comes from authentication. The caller supplies the client and optional business justification. The server assigns the request identifier and current UTC month. Billing grants do not widen this route. Requires shared Platform authentication with the required scope, experimental opt-in, and the existing request-more enablement flag. Missing opt-in or a disabled flag returns 404. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformPersonalRequestCreate" description: Personal request for the authenticated user and specified client. example: client_id: glean responses: "201": $ref: "#/components/responses/PlatformRequestResource" description: The created personal request. "400": $ref: "#/components/responses/PlatformBadRequest" description: Invalid input, with field-level validation details when available. "401": $ref: "#/components/responses/PlatformUnauthorized" description: Authentication is missing or invalid. "403": $ref: "#/components/responses/PlatformForbidden" description: The caller lacks the required scope or current resource permission. "404": $ref: "#/components/responses/PlatformNotFound" description: | Experimental opt-in is missing, the enablement flag is disabled, or the request is missing or inaccessible. "408": $ref: "#/components/responses/PlatformRequestTimeout" description: The operation timed out. "409": $ref: "#/components/responses/PlatformConflict" description: The request conflicts with the current stored request state. "413": $ref: "#/components/responses/PlatformRequestTooLarge" description: The request exceeds the supported body size. "429": $ref: "#/components/responses/PlatformTooManyRequests" description: The caller exceeded the request rate limit. "500": $ref: "#/components/responses/PlatformInternalServerError" description: An unexpected internal error prevented completion. "503": $ref: "#/components/responses/PlatformServiceUnavailable" description: The operation is unsupported or temporarily unavailable; ONGOING approval is unsupported. x-speakeasy-group: usage x-speakeasy-name-override: createLimitIncreaseRequest get: tags: - Usage summary: List personal limit-increase requests operationId: platform-usage-requests-list x-glean-scopes: legacy: - USAGE_LIMIT_INCREASE_REQUESTS platform: - usage.limit_increase_requests:read x-visibility: Public x-glean-experimental: id: d92d077c-81c0-4d91-868d-021eed013d8d introduced: "2026-09-25" description: | Requires usage.limit_increase_requests:read. The collection is limited to the authenticated canonical user's requests, including resolved requests. Cursors bind the filters and current authorization context; a billing grant cannot widen results. Supported token issuance, experimental opt-in, and request-more enablement are required. Missing opt-in or a disabled flag returns 404. parameters: - $ref: "#/components/parameters/PageSize" description: Maximum page size; defaults to 20 and cannot exceed 100. - $ref: "#/components/parameters/Cursor" description: Opaque continuation bound to filters and current authorization. - $ref: "#/components/parameters/Filters" description: Optional structured filters on request status. responses: "200": description: A bounded page of authorized requests. content: application/json: schema: $ref: "#/components/schemas/PlatformRequestListResponse" description: Authorized request page and continuation state. "400": $ref: "#/components/responses/PlatformBadRequest" description: Invalid input, with field-level validation details when available. "401": $ref: "#/components/responses/PlatformUnauthorized" description: Authentication is missing or invalid. "403": $ref: "#/components/responses/PlatformForbidden" description: The caller lacks the required scope or current resource permission. "404": $ref: "#/components/responses/PlatformNotFound" description: | Experimental opt-in is missing, the enablement flag is disabled, or the request is missing or inaccessible. "408": $ref: "#/components/responses/PlatformRequestTimeout" description: The operation timed out. "429": $ref: "#/components/responses/PlatformTooManyRequests" description: The caller exceeded the request rate limit. "500": $ref: "#/components/responses/PlatformInternalServerError" description: An unexpected internal error prevented completion. "503": $ref: "#/components/responses/PlatformServiceUnavailable" description: The operation is unsupported or temporarily unavailable; ONGOING approval is unsupported. x-speakeasy-group: usage x-speakeasy-name-override: listLimitIncreaseRequests /api/usage/limit-increase-requests/{request_id}: parameters: - $ref: "#/components/parameters/RequestId" description: Opaque personal request identifier; not an authorization grant. get: tags: - Usage summary: Get a personal limit-increase request operationId: platform-usage-requests-get x-glean-scopes: legacy: - USAGE_LIMIT_INCREASE_REQUESTS platform: - usage.limit_increase_requests:read x-visibility: Public x-glean-experimental: id: 29a2f132-a0c2-429f-95e7-7995de058cd3 introduced: "2026-09-25" description: | Requires usage.limit_increase_requests:read and the current user's request. Authorization precedes resource disclosure. Missing and inaccessible records return the same 404. Supported token issuance, experimental opt-in, and request-more enablement are required. Missing opt-in or a disabled flag also returns 404. responses: "200": $ref: "#/components/responses/PlatformRequestResource" description: The authorized request in its current stored state. "400": $ref: "#/components/responses/PlatformBadRequest" description: Invalid input, with field-level validation details when available. "401": $ref: "#/components/responses/PlatformUnauthorized" description: Authentication is missing or invalid. "403": $ref: "#/components/responses/PlatformForbidden" description: The caller lacks the required scope or current resource permission. "404": $ref: "#/components/responses/PlatformNotFound" description: | Experimental opt-in is missing, the enablement flag is disabled, or the request is missing or inaccessible. "408": $ref: "#/components/responses/PlatformRequestTimeout" description: The operation timed out. "429": $ref: "#/components/responses/PlatformTooManyRequests" description: The caller exceeded the request rate limit. "500": $ref: "#/components/responses/PlatformInternalServerError" description: An unexpected internal error prevented completion. "503": $ref: "#/components/responses/PlatformServiceUnavailable" description: The operation is unsupported or temporarily unavailable; ONGOING approval is unsupported. x-speakeasy-group: usage x-speakeasy-name-override: getLimitIncreaseRequest /api/admin/usage/limit-increase-requests: post: tags: - Usage summary: Submit an editable-agent limit-increase request operationId: platform-admin-usage-requests-create x-glean-scopes: legacy: - USAGE_LIMIT_INCREASE_REQUESTS platform: - usage.limit_increase_requests:write x-visibility: Public x-glean-experimental: id: e28f40de-1f6c-4dc6-ab12-4054b89628c1 introduced: "2026-09-25" description: | Requires usage.limit_increase_requests:write, the same scope as personal creation, and current edit permission on the agent, not billing permissions. The caller supplies the agent, client, and optional business justification. Requester identity comes from authentication; the server assigns the request identifier and current UTC month. Requires shared Platform authentication with the required scope, experimental opt-in, and the existing request-more enablement flag. Missing opt-in or a disabled flag returns 404. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformAgentRequestCreate" description: Client-scoped request for an agent the caller can edit. example: agent_id: "{agent_id}" client_id: glean responses: "201": $ref: "#/components/responses/PlatformRequestResource" description: The created editable-agent request. "400": $ref: "#/components/responses/PlatformBadRequest" description: Invalid input, with field-level validation details when available. "401": $ref: "#/components/responses/PlatformUnauthorized" description: Authentication is missing or invalid. "403": $ref: "#/components/responses/PlatformForbidden" description: The caller lacks the required scope or current resource permission. "404": $ref: "#/components/responses/PlatformNotFound" description: | Experimental opt-in is missing, the enablement flag is disabled, or the request is missing or inaccessible. "408": $ref: "#/components/responses/PlatformRequestTimeout" description: The operation timed out. "409": $ref: "#/components/responses/PlatformConflict" description: The request conflicts with the current stored request state. "413": $ref: "#/components/responses/PlatformRequestTooLarge" description: The request exceeds the supported body size. "429": $ref: "#/components/responses/PlatformTooManyRequests" description: The caller exceeded the request rate limit. "500": $ref: "#/components/responses/PlatformInternalServerError" description: An unexpected internal error prevented completion. "503": $ref: "#/components/responses/PlatformServiceUnavailable" description: The operation is unsupported or temporarily unavailable; ONGOING approval is unsupported. x-speakeasy-group: admin.usage x-speakeasy-name-override: createLimitIncreaseRequest get: tags: - Usage summary: List the billing limit-increase request queue operationId: platform-admin-usage-requests-list x-glean-scopes: legacy: - ADMIN_USAGE_LIMIT_INCREASE_REQUESTS platform: - admin.usage.limit_increase_requests:read x-visibility: Public x-glean-experimental: id: b02bb653-00f9-4739-b387-90f68c7385ee introduced: "2026-09-25" description: | Requires admin.usage.limit_increase_requests:read and current workspace billing read permission. Agent ownership is not queue access. Cursors bind filters and current authorization context. Supported token issuance, experimental opt-in, and request-more enablement are required. Missing opt-in or a disabled flag returns 404, not a successful empty page. parameters: - $ref: "#/components/parameters/PageSize" description: Maximum page size; defaults to 20 and cannot exceed 100. - $ref: "#/components/parameters/Cursor" description: Opaque continuation bound to filters and current authorization. - $ref: "#/components/parameters/Filters" description: Optional structured filters on request status. responses: "200": description: A bounded page of authorized requests. content: application/json: schema: $ref: "#/components/schemas/PlatformRequestListResponse" description: Authorized request page and continuation state. "400": $ref: "#/components/responses/PlatformBadRequest" description: Invalid input, with field-level validation details when available. "401": $ref: "#/components/responses/PlatformUnauthorized" description: Authentication is missing or invalid. "403": $ref: "#/components/responses/PlatformForbidden" description: The caller lacks the required scope or current resource permission. "404": $ref: "#/components/responses/PlatformNotFound" description: | Experimental opt-in is missing, the enablement flag is disabled, or the request is missing or inaccessible. "408": $ref: "#/components/responses/PlatformRequestTimeout" description: The operation timed out. "429": $ref: "#/components/responses/PlatformTooManyRequests" description: The caller exceeded the request rate limit. "500": $ref: "#/components/responses/PlatformInternalServerError" description: An unexpected internal error prevented completion. "503": $ref: "#/components/responses/PlatformServiceUnavailable" description: The operation is unsupported or temporarily unavailable; ONGOING approval is unsupported. x-speakeasy-group: admin.usage x-speakeasy-name-override: listLimitIncreaseRequests /api/admin/usage/limit-increase-requests/{request_id}: parameters: - $ref: "#/components/parameters/RequestId" description: Opaque request identifier; not an authorization grant. get: tags: - Usage summary: Get a billing limit-increase request operationId: platform-admin-usage-requests-get x-glean-scopes: legacy: - ADMIN_USAGE_LIMIT_INCREASE_REQUESTS platform: - admin.usage.limit_increase_requests:read x-visibility: Public x-glean-experimental: id: 88f1a13a-3e09-4c78-a2dc-87cc223dc003 introduced: "2026-09-25" description: | Requires admin.usage.limit_increase_requests:read and current workspace billing read permission. Authorization precedes resource disclosure. Owner-only agent reads are not supported. Supported token issuance, experimental opt-in, and request-more enablement are required. Missing opt-in or a disabled flag returns 404. responses: "200": $ref: "#/components/responses/PlatformRequestResource" description: The authorized request in its current stored state. "400": $ref: "#/components/responses/PlatformBadRequest" description: Invalid input, with field-level validation details when available. "401": $ref: "#/components/responses/PlatformUnauthorized" description: Authentication is missing or invalid. "403": $ref: "#/components/responses/PlatformForbidden" description: The caller lacks the required scope or current resource permission. "404": $ref: "#/components/responses/PlatformNotFound" description: | Experimental opt-in is missing, the enablement flag is disabled, or the request is missing or inaccessible. "408": $ref: "#/components/responses/PlatformRequestTimeout" description: The operation timed out. "429": $ref: "#/components/responses/PlatformTooManyRequests" description: The caller exceeded the request rate limit. "500": $ref: "#/components/responses/PlatformInternalServerError" description: An unexpected internal error prevented completion. "503": $ref: "#/components/responses/PlatformServiceUnavailable" description: The operation is unsupported or temporarily unavailable; ONGOING approval is unsupported. x-speakeasy-group: admin.usage x-speakeasy-name-override: getLimitIncreaseRequest patch: tags: - Usage summary: Resolve a billing limit-increase request operationId: platform-admin-usage-requests-update x-glean-scopes: legacy: - ADMIN_USAGE_LIMIT_INCREASE_REQUESTS platform: - admin.usage.limit_increase_requests:write x-visibility: Public x-glean-experimental: id: 08d999ca-f438-4fed-81ce-350c7e65c2cc introduced: "2026-09-25" description: | Update a pending request with an approval decision or denial. Requires admin.usage.limit_increase_requests:write and current billing edit permission. A pending request can record an approved positive increase amount or be denied with an optional resolution note. PERIOD approval retains the request's stored month and requires the current UTC month; expired approvals return 409 before mutation or approval writes. A successful approval write triggers spend-limit cache refresh before reload; refresh failure logs a warning without failing the decision. The existing backend consumes eligible USER current-period grants to raise enforcement headroom without changing standing rules. This does not add capacity for agents or other unsupported targets, integrate usage settings, or promise new delivery or atomicity guarantees. Supported token issuance, experimental opt-in, and request-more enablement are required. Missing opt-in or a disabled flag returns 404. Once enabled and opted in, ONGOING returns typed 503 without reading or modifying the request; its private policy preparation is not shared with this adapter. Use the existing app operation for ongoing user approvals. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformAdministrativeRequestUpdate" description: Record a PERIOD approval decision or denial of a pending request. example: status: APPROVED approved_increase_amount: "100.00" scope: PERIOD responses: "200": $ref: "#/components/responses/PlatformRequestResource" description: The resolved request in its current stored state. "400": $ref: "#/components/responses/PlatformBadRequest" description: Invalid input, with field-level validation details when available. "401": $ref: "#/components/responses/PlatformUnauthorized" description: Authentication is missing or invalid. "403": $ref: "#/components/responses/PlatformForbidden" description: The caller lacks the required scope or current resource permission. "404": $ref: "#/components/responses/PlatformNotFound" description: | Experimental opt-in is missing, the enablement flag is disabled, or the request is missing or inaccessible. "408": $ref: "#/components/responses/PlatformRequestTimeout" description: The operation timed out. "409": $ref: "#/components/responses/PlatformConflict" description: The request conflicts with the current stored request state. "413": $ref: "#/components/responses/PlatformRequestTooLarge" description: The request exceeds the supported body size. "429": $ref: "#/components/responses/PlatformTooManyRequests" description: The caller exceeded the request rate limit. "500": $ref: "#/components/responses/PlatformInternalServerError" description: An unexpected internal error prevented completion. "503": $ref: "#/components/responses/PlatformServiceUnavailable" description: The operation is unsupported or temporarily unavailable; ONGOING approval is unsupported. x-speakeasy-group: admin.usage x-speakeasy-name-override: updateLimitIncreaseRequest /api/admin/oauth/clients: get: tags: - OAuth clients summary: List OAuth clients description: | List the static OAuth clients that admins created for this workspace, ordered by display_name and then by client_id. Dynamically registered clients and Glean's own clients, such as Glean Desktop, are not listed. A client is active when it is enabled. Inactive clients are left out unless an is_active filter includes the value "false". To set a usage limit for a client, send its ai_gateway.usage_client_id, not its client_id, to the usage APIs. The caller needs admin read or billing read permission. operationId: platform-admin-oauth-clients-list x-glean-scopes: legacy: - ADMIN - ADMIN_USAGE platform: - admin.oauth.clients:read x-visibility: Public x-glean-experimental: id: 0be15d1f-0e4f-49f8-9dd1-1746b019abd7 introduced: "2026-10-09" parameters: - in: query name: page_size description: Maximum number of clients to return. Defaults to 50. Maximum is 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: cursor description: | Opaque pagination cursor from a previous response. Send the same filters that the previous request used. required: false schema: type: string minLength: 1 - in: query name: filters description: | JSON-encoded filters that choose which clients are returned. The only supported field is is_active, with the values "true" and "false" and the operator EQUALS. Multiple values OR within a filter. Multiple filters AND together. Without an is_active filter, only active clients are returned. To return active and inactive clients, send [{"field":"is_active","values":["true","false"]}]. required: false content: application/json: schema: type: array minItems: 1 maxItems: 10 description: Filters on client fields, combined with AND. items: $ref: "#/components/schemas/PlatformOAuthClientFilter" description: One filter on a client field. responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformListOAuthClientsResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.oauth.clients x-speakeasy-name-override: list /api/departments: get: tags: - Departments summary: List departments description: | List the departments in the Glean directory, ordered by display_name and then by department_id. A department is active when at least one active user belongs to it. A department is inactive when only inactive users, such as former employees, belong to it, or when only a usage limit names it. Inactive departments are left out unless an is_active filter includes the value "false". Department names are exact, so names that differ only by case are different departments. operationId: platform-departments-list x-glean-scopes: legacy: - PEOPLE platform: - departments:read x-visibility: Public x-glean-experimental: id: 2bc9ce31-8e51-4874-996c-96ad2e10fbd7 introduced: "2026-10-08" parameters: - in: query name: page_size description: Maximum number of departments to return. Defaults to 50. Maximum is 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: cursor description: | Opaque pagination cursor from a previous response. Send the same filters that the previous request used. required: false schema: type: string minLength: 1 - in: query name: filters description: | JSON-encoded filters that choose which departments are returned. The only supported field is is_active, with the values "true" and "false" and the operator EQUALS. Multiple values OR within a filter. Multiple filters AND together. Without an is_active filter, only active departments are returned. To return active and inactive departments, send [{"field":"is_active","values":["true","false"]}]. required: false content: application/json: schema: type: array minItems: 1 maxItems: 10 description: Filters on department fields, combined with AND. items: $ref: "#/components/schemas/PlatformDepartmentFilter" description: One filter on a department field. responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformListDepartmentsResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: departments x-speakeasy-name-override: list /api/admin/idp-groups: get: tags: - IdP Groups summary: List IdP groups description: | List the identity provider (IdP) groups that Glean loads from the directory, ordered by display_name and then by idp_group_id. Use idp_group_id to name a group in other Platform APIs. An IdP group is active when Glean loaded it from the directory. An IdP group is inactive when only a usage limit names it, for example after the group was removed from the identity provider. Inactive IdP groups are left out unless an is_active filter includes the value "false". Usage limits apply only to IdP groups from the datasource instance that the usage settings select, so use the provider_instance filter to list only those groups. Internal O365 ownership groups and SharePoint groups are left out. The caller must be able to read the workspace configuration or the workspace billing. operationId: platform-admin-idp-groups-list x-glean-scopes: legacy: - ADMIN - ADMIN_USAGE platform: - admin.idp_groups:read x-visibility: Public x-glean-experimental: id: 416f645e-926e-4fb5-b9b1-03d0e7366097 introduced: "2026-10-09" parameters: - in: query name: page_size description: Maximum number of IdP groups to return. Defaults to 50. Maximum is 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: cursor description: | Opaque pagination cursor from a previous response. Send the same filters that the previous request used. required: false schema: type: string minLength: 1 - in: query name: filters description: | JSON-encoded filters that choose which IdP groups are returned. The supported fields are is_active, with the values "true" and "false", and provider_instance, with datasource instance names such as "okta". provider_instance values match without case. The only supported operator is EQUALS. Multiple values OR within a filter. Multiple filters AND together. Without an is_active filter, only active IdP groups are returned. To return active and inactive IdP groups, send [{"field":"is_active","values":["true","false"]}]. required: false content: application/json: schema: type: array minItems: 1 maxItems: 10 description: Filters on IdP group fields, combined with AND. items: $ref: "#/components/schemas/PlatformIdpGroupFilter" description: One filter on an IdP group field. responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformListIdpGroupsResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.idpgroups x-speakeasy-name-override: list /api/users: get: tags: - Users summary: List users description: | List the users in the Glean directory, ordered by display_name and then by user_id. The list includes the same people as the Glean People directory. Inactive users, such as former employees, are left out unless an is_active filter includes the value "false". Use the returned user_id values with other Platform APIs, for example as usage limit targets. operationId: platform-users-list x-glean-scopes: legacy: - PEOPLE platform: - users:read x-visibility: Public x-glean-experimental: id: 284483b2-925a-412f-a60d-891c699307f6 introduced: "2026-10-07" parameters: - in: query name: page_size description: Maximum number of users to return. Defaults to 50. Maximum is 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: cursor description: | Opaque pagination cursor from a previous response. Send the same filters that the previous request used. required: false schema: type: string minLength: 1 - in: query name: filters description: | JSON-encoded filters that choose which users are returned. The only supported field is is_active, with the values "true" and "false" and the operator EQUALS. Multiple values OR within a filter. Multiple filters AND together. Without an is_active filter, only active users are returned. To return active and inactive users, send [{"field":"is_active","values":["true","false"]}]. required: false content: application/json: schema: type: array minItems: 1 maxItems: 10 description: Filters on user fields, combined with AND. items: $ref: "#/components/schemas/PlatformUserFilter" description: One filter on a user field. - in: query name: include description: | Optional fields to add to each user. Each value only adds fields; it does not change which users are returned. required: false style: form explode: true schema: type: array items: $ref: "#/components/schemas/PlatformUserInclude" responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformListUsersResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: users x-speakeasy-name-override: list /api/admin/agents: get: tags: - Agents summary: List all agents description: | List every agent in the workspace, ordered by display_name and then by agent_id. Unlike agent search, the list does not depend on who an agent is shared with, so it includes private and disabled agents. Deleted agents are inactive and are left out unless an is_active filter includes the value "false". Use the agent_id of an active agent with other Platform APIs, for example as a usage limit target. A deleted agent is not a valid usage limit target. The caller must be able to read all agents, administer agents, or read workspace billing. operationId: platform-admin-agents-list x-glean-scopes: legacy: - ADMIN - ADMIN_USAGE platform: - admin.agents:read x-visibility: Public x-glean-experimental: id: 8f66e1bd-eb48-4381-88f2-697a0e51ccc7 introduced: "2026-10-08" parameters: - in: query name: page_size description: Maximum number of agents to return. Defaults to 50. Maximum is 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: cursor description: | Opaque pagination cursor from a previous response. Send the same filters that the previous request used. required: false schema: type: string minLength: 1 - in: query name: filters description: | JSON-encoded filters that choose which agents are returned. The only supported field is is_active, with the values "true" and "false" and the operator EQUALS. Multiple values OR within a filter. Multiple filters AND together. Without an is_active filter, only active agents are returned. To return active and deleted agents, send [{"field":"is_active","values":["true","false"]}]. required: false content: application/json: schema: type: array minItems: 1 maxItems: 10 description: Filters on agent fields, combined with AND. items: $ref: "#/components/schemas/PlatformAdminAgentFilter" description: One filter on an agent field. responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformListAdminAgentsResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: admin.agents x-speakeasy-name-override: list /api/triggers: post: tags: - Triggers summary: Create trigger description: | Create a trigger from a preset and return it with its signing secret. operationId: platform-triggers-create x-glean-scopes: legacy: - TRIGGERS platform: - triggers:write x-visibility: Public x-glean-experimental: id: eb175f18-74e6-4c9c-ba02-23bcc9018fc9 introduced: "2026-07-06" x-codegen-request-body-name: payload requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerCreateRequest" callbacks: triggerEvent: "{$request.body#/delivery/webhook_url}": post: tags: - Triggers summary: Receive a trigger event description: Delivery uses at-least-once semantics, so the same event can be sent more than once. Return any 2xx status after accepting the event. Network failures, 408, 429, and 5xx responses are retried; other non-2xx responses, including redirects, are terminal. The `webhook-id` remains stable across attempts and can be used for deduplication, while `webhook-timestamp` and `webhook-signature` are generated for each attempt. operationId: trigger-webhook-event security: - {} - TriggerWebhookBearerAuth: [] parameters: - $ref: "#/components/parameters/TriggerWebhookId" - $ref: "#/components/parameters/TriggerWebhookTimestamp" - $ref: "#/components/parameters/TriggerWebhookSignature" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerWebhookEvent" responses: "408": description: Request timeout. Glean retries the delivery. "429": description: Rate limited. Glean retries the delivery. 2XX: description: Event accepted. Glean does not retry the delivery. 3XX: description: Redirects are not followed and the delivery is not retried. 4XX: description: Client error other than 408 or 429. Glean does not retry. 5XX: description: Server error. Glean retries the delivery. responses: "201": description: Trigger created. content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerCreateResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "409": $ref: "#/components/responses/PlatformConflict" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: create get: tags: - Triggers summary: List triggers description: | List triggers owned by the authenticated caller. operationId: platform-triggers-list x-glean-scopes: legacy: - TRIGGERS platform: - triggers:read x-visibility: Public x-glean-experimental: id: e3554987-e043-4561-889a-a1117b1bce06 introduced: "2026-07-06" parameters: - in: query name: page_size description: Maximum number of triggers to return. required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: cursor description: Opaque pagination cursor from a previous response. required: false schema: type: string minLength: 1 responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerListResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: list /api/triggers/{trigger_id}: get: tags: - Triggers summary: Get trigger description: | Retrieve a trigger owned by the authenticated caller. operationId: platform-triggers-get x-glean-scopes: legacy: - TRIGGERS platform: - triggers:read x-visibility: Public x-glean-experimental: id: 46de62cb-ba31-4f71-9646-649c1d604816 introduced: "2026-07-06" parameters: - in: path name: trigger_id description: ID of the trigger to retrieve. required: true example: "{trigger_id}" schema: type: string minLength: 1 responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerGetResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: get patch: tags: - Triggers summary: Update trigger description: | Update a trigger. operationId: platform-triggers-update x-glean-scopes: legacy: - TRIGGERS platform: - triggers:write x-visibility: Public x-glean-experimental: id: 3eb4c709-bd5c-4019-b913-0db36c766350 introduced: "2026-07-06" x-codegen-request-body-name: payload parameters: - in: path name: trigger_id description: ID of the trigger to update. required: true example: "{trigger_id}" schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerUpdateRequest" responses: "200": description: Trigger updated. content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerGetResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: update delete: tags: - Triggers summary: Delete trigger description: | Delete a trigger. operationId: platform-triggers-delete x-glean-scopes: legacy: - TRIGGERS platform: - triggers:write x-visibility: Public x-glean-experimental: id: e6564ed7-8b4b-4708-918b-eed97110859f introduced: "2026-07-06" parameters: - in: path name: trigger_id description: ID of the trigger to delete. required: true example: "{trigger_id}" schema: type: string minLength: 1 responses: "204": description: Trigger deleted. No content. "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: delete /api/triggers/{trigger_id}/events/search: post: tags: - Triggers summary: Search events for a trigger description: | Search recent content events an existing trigger matches. Read-only — no webhook delivery is made. Covers the last seven days. operationId: platform-triggers-events-search x-glean-scopes: legacy: - TRIGGERS platform: - triggers:read x-visibility: Public x-glean-experimental: id: c734a377-3dec-4ee2-9ec5-3848a8384f03 introduced: "2026-08-07" parameters: - in: path name: trigger_id description: ID of the trigger whose events to search. required: true example: "{trigger_id}" schema: type: string minLength: 1 requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerEventSearchRequest" responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerEventSearchResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: searchEvents /api/trigger-presets: get: tags: - Triggers summary: List trigger presets description: | List the trigger presets available to the caller. A preset is a curated content-trigger template (e.g. a new Jira ticket) which is passed when creating a trigger. operationId: platform-trigger-presets-list x-glean-scopes: legacy: - TRIGGERS platform: - triggers:read x-visibility: Public x-glean-experimental: id: f5b16196-0d4c-42f0-89bf-40313398728e introduced: "2026-07-22" parameters: - in: query name: datasource description: Restrict results to presets for a single datasource (e.g. github). required: false schema: type: string minLength: 1 - in: query name: page_size description: Maximum number of presets to return. required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: cursor description: Opaque pagination cursor from a previous response. required: false schema: type: string minLength: 1 responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerPresetListResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: listPresets /api/trigger-presets/{preset_id}: get: tags: - Triggers summary: Get trigger preset description: | Retrieve a single trigger preset by id. operationId: platform-trigger-presets-get x-glean-scopes: legacy: - TRIGGERS platform: - triggers:read x-visibility: Public x-glean-experimental: id: 5277167d-909b-4eee-95d1-8958b07016bb introduced: "2026-07-22" parameters: - in: path name: preset_id description: ID of the preset to retrieve. required: true example: "{preset_id}" schema: type: string minLength: 1 responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerPresetGetResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: getPreset /api/trigger-presets/{preset_id}/input-values: get: tags: - Triggers summary: Search trigger preset input values description: | Return up to 300 selectable values for a single picklist input on a preset. Results are intended for typeahead selection and are not cursor-paginated. When `is_truncated` is true, refine `query` to narrow the result set. operationId: platform-trigger-presets-input-values-list x-glean-scopes: legacy: - TRIGGERS platform: - triggers:read x-visibility: Public x-glean-experimental: id: 24c5675d-a57a-48cb-9d71-3dece296f28c introduced: "2026-08-06" parameters: - in: path name: preset_id description: ID of the preset the input belongs to. required: true example: "{preset_id}" schema: type: string minLength: 1 - in: query name: field description: Field identifier of the input whose values to list. required: true example: "{field}" schema: type: string minLength: 1 - in: query name: query description: | Prefix filter over the input's option values, for typeahead. Matching is on the option value, not its display name. required: false schema: type: string responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerPresetInputValueListResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: listPresetInputValues /api/trigger-presets/{preset_id}/events/search: post: tags: - Triggers summary: Search events for a trigger preset description: | Search recent content events an unsaved trigger built from this preset would match, to preview it before creating the trigger. Read-only — no trigger is created and no webhook delivery is made. Covers the last seven days. operationId: platform-trigger-presets-events-search x-glean-scopes: legacy: - TRIGGERS platform: - triggers:read x-visibility: Public x-glean-experimental: id: a48efd80-78d6-46de-9f23-5b8c63ecd157 introduced: "2026-08-12" parameters: - in: path name: preset_id description: ID of the preset to preview. required: true example: "{preset_id}" schema: type: string minLength: 1 requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerPresetEventSearchRequest" responses: "200": description: Successful response. content: application/json: schema: $ref: "#/components/schemas/PlatformTriggerEventSearchResponse" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: triggers x-speakeasy-name-override: searchPresetEvents /api/chat#stream: post: tags: - Chat summary: Create a streaming chat response description: | SDK-only logical operation. HTTP clients must call the base path; the URL fragment is not sent. Run an assistant turn as server-sent events. HTTP clients request this mode by setting `stream` to true in the JSON body. operationId: platform-chat-create-stream x-glean-scopes: legacy: - CHAT platform: - chat:write x-visibility: Public x-codegen-request-body-name: payload requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/PlatformChatCreateRequest" - type: object required: - stream properties: stream: type: boolean const: true default: true responses: "200": description: Successful response. content: text/event-stream: schema: $ref: "#/components/schemas/PlatformChatStreamEventServerSentEvent" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "404": $ref: "#/components/responses/PlatformNotFound" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "422": $ref: "#/components/responses/PlatformUnprocessableEntity" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: chat x-speakeasy-name-override: createStream /api/skills/sources/preview#stream: post: tags: - Skills summary: Preview a GitHub skill source as events description: | SDK-only logical operation. HTTP clients must call the base path; the URL fragment is not sent. Inspect a GitHub URL as server-sent events. HTTP clients request this mode by setting `stream` to true in the JSON body. operationId: platform-skills-preview-source-stream x-glean-scopes: legacy: - SKILLS platform: - skills:write x-visibility: Public x-codegen-request-body-name: request requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/PlatformSkillSourcePreviewRequest" - type: object required: - stream properties: stream: type: boolean const: true default: true responses: "200": description: Successful response. content: text/event-stream: schema: $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamEventServerSentEvent" "400": $ref: "#/components/responses/PlatformBadRequest" "401": $ref: "#/components/responses/PlatformUnauthorized" "403": $ref: "#/components/responses/PlatformForbidden" "408": $ref: "#/components/responses/PlatformRequestTimeout" "413": $ref: "#/components/responses/PlatformRequestTooLarge" "422": description: Returned when GitHub authorization is missing for the source URL. `authentication_suggestions` names the GitHub action pack to authorize; POST its `server_id` to the Client API's `/tool-servers/{serverId}/auth` with `returnUrl` in the request body to obtain an `authorizationUrl` to redirect the end user to, then retry the preview once OAuth completes. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformUnauthorizedAgentToolsProblem" "429": $ref: "#/components/responses/PlatformTooManyRequests" "500": $ref: "#/components/responses/PlatformInternalServerError" "503": $ref: "#/components/responses/PlatformServiceUnavailable" x-speakeasy-group: skills x-speakeasy-name-override: previewSourceStream components: securitySchemes: APIToken: type: http scheme: bearer description: | Glean API token. Obtain via Admin Console -> Platform -> API Tokens, or via OAuth 2.0 client credentials flow. schemas: PlatformWarning: type: object additionalProperties: false required: - code - message description: Non-blocking warning attached to a successful Platform response. properties: code: type: string minLength: 1 description: | Open snake_case warning code. Clients must tolerate unknown values; the set of codes is not a closed enum. example: results_incomplete message: type: string minLength: 1 description: Human-readable warning message. PlatformAgentsSearchRequest: type: object additionalProperties: false example: name: HR Policy Agent properties: name: type: string description: Case-insensitive substring to match against agent names. If omitted or empty, no name filter is applied. example: HR Policy Agent PlatformAgentCapabilities: type: object additionalProperties: true properties: ap.io.messages: type: boolean description: Whether the agent supports messages as input. ap.io.streaming: type: boolean description: Whether the agent supports streaming output. PlatformAgent: type: object required: - agent_id - name - capabilities properties: agent_id: type: string description: ID of the agent. example: mho4lwzylcozgoc2 name: type: string description: Name of the agent. example: HR Policy Agent description: type: string description: Description of the agent. metadata: type: object description: Agent metadata. additionalProperties: true capabilities: $ref: "#/components/schemas/PlatformAgentCapabilities" PlatformAgentsSearchResponse: type: object required: - agents - request_id properties: agents: type: array description: Agents matching the search request. items: $ref: "#/components/schemas/PlatformAgent" request_id: type: string description: Platform-generated request ID for support correlation. PlatformProblemDetailCode: type: string description: Stable machine-readable error code. enum: - invalid_request - missing_required_field - invalid_parameter - invalid_cursor - expired_cursor - invalid_filter - invalid_datasource - authentication_required - token_expired - insufficient_permissions - spend_limit_exceeded - resource_not_found - method_not_allowed - request_timeout - request_too_large - token_limit_exceeded - conflict - gone - unprocessable_query - tools_unauthorized - rate_limit_exceeded - internal_error - service_unavailable x-glean-problem-detail-codes: invalid_request: status: 400 title: Invalid Request missing_required_field: status: 400 title: Missing Required Field invalid_parameter: status: 400 title: Invalid Parameter invalid_cursor: status: 400 title: Invalid Pagination Cursor expired_cursor: status: 400 title: Expired Pagination Cursor invalid_filter: status: 400 title: Invalid Filter invalid_datasource: status: 400 title: Invalid Datasource authentication_required: status: 401 title: Authentication Required token_expired: status: 401 title: Token Expired insufficient_permissions: status: 403 title: Insufficient Permissions spend_limit_exceeded: status: 403 title: Spend Limit Exceeded resource_not_found: status: 404 title: Resource Not Found method_not_allowed: status: 405 title: Method Not Allowed request_timeout: status: 408 title: Request Timeout request_too_large: status: 413 title: Request Too Large token_limit_exceeded: status: 413 title: Token Limit Exceeded conflict: status: 409 title: Conflict gone: status: 410 title: Gone unprocessable_query: status: 422 title: Unprocessable Query tools_unauthorized: status: 422 title: Tools Unauthorized rate_limit_exceeded: status: 429 title: Rate Limit Exceeded internal_error: status: 500 title: Internal Error service_unavailable: status: 503 title: Service Unavailable example: invalid_cursor PlatformProblemDetailError: type: object required: - pointer - detail description: Field-level validation problem for a single offending field. properties: pointer: type: string description: RFC 6901 JSON Pointer to the offending field. example: /messages/0/role detail: type: string description: Human-readable explanation for this field. example: "Must be one of: USER, GLEAN_AI." code: $ref: "#/components/schemas/PlatformProblemDetailCode" PlatformProblemDetail: type: object required: - type - title - status - detail - code - request_id description: | Error response following RFC 9457, extended with `code` and `documentation_url` for machine-readable classification and self-service remediation. properties: type: type: string format: uri description: URI identifying the error type. example: https://developers.glean.com/errors/invalid-cursor title: type: string description: Short, human-readable summary of the error. example: Invalid Pagination Cursor status: type: integer description: HTTP status code mirrored from the response. example: 400 detail: type: string description: Human-readable explanation specific to this occurrence. example: | The provided cursor has expired. Start a new search to get a fresh cursor. code: $ref: "#/components/schemas/PlatformProblemDetailCode" documentation_url: type: string format: uri description: Direct URL to documentation for this error code. example: https://developers.glean.com/errors/invalid-cursor request_id: type: string description: Platform-generated request ID for support correlation. example: req_7f8a9b0c1d2e errors: type: array description: Field-level validation problems, one entry per offending field. items: $ref: "#/components/schemas/PlatformProblemDetailError" PlatformAgentGetResponse: type: object required: - agent - request_id properties: agent: $ref: "#/components/schemas/PlatformAgent" request_id: type: string description: Platform-generated request ID for support correlation. PlatformActionSummary: type: object required: - tool_id - display_name properties: tool_id: type: string description: Unique identifier of the action. display_name: type: string description: Display name of the action. type: type: string description: Tool type. auth_type: type: string description: Authentication type required by the action. write_action_type: type: string description: Write-action execution type. is_setup_finished: type: boolean description: Whether this action has been fully configured. data_source: type: string description: Kind of knowledge the action accesses or modifies. PlatformAgentSchemasResponse: type: object required: - agent_id - input_schema - output_schema - request_id properties: agent_id: type: string description: ID of the agent. name: type: string description: Name of the agent. input_schema: type: object description: Agent input schema in JSON Schema format. additionalProperties: true output_schema: type: object description: Agent output schema in JSON Schema format. additionalProperties: true tools: type: array description: Tools that the agent can invoke, when requested. items: $ref: "#/components/schemas/PlatformActionSummary" request_id: type: string description: Platform-generated request ID for support correlation. PlatformMessageRole: type: string description: Role of the message author. example: USER enum: - USER - GLEAN_AI PlatformContentType: type: string enum: - text PlatformChatDocumentSource: type: object additionalProperties: false required: - type properties: type: type: string x-discriminator: true enum: - DOCUMENT document_id: type: string minLength: 1 url: type: string minLength: 1 title: type: string datasource: type: string anyOf: - required: - document_id properties: document_id: type: string minLength: 1 - required: - url properties: url: type: string minLength: 1 PlatformChatPersonSource: type: object additionalProperties: false required: - type - person_id properties: type: type: string x-discriminator: true enum: - PERSON person_id: type: string minLength: 1 name: type: string url: type: string PlatformChatFileSource: type: object additionalProperties: false required: - type - file_id properties: type: type: string x-discriminator: true enum: - FILE file_id: type: string minLength: 1 title: type: string url: type: string datasource: type: string PlatformChatCustomEntitySource: type: object additionalProperties: false required: - type - entity_id properties: type: type: string x-discriminator: true enum: - CUSTOM_ENTITY entity_id: type: string minLength: 1 name: type: string title: type: string url: type: string datasource: type: string PlatformChatCitationSource: description: Four-variant citation source union. x-multiple-discriminators: true oneOf: - $ref: "#/components/schemas/PlatformChatDocumentSource" - $ref: "#/components/schemas/PlatformChatPersonSource" - $ref: "#/components/schemas/PlatformChatFileSource" - $ref: "#/components/schemas/PlatformChatCustomEntitySource" discriminator: propertyName: type mapping: DOCUMENT: "#/components/schemas/PlatformChatDocumentSource" PERSON: "#/components/schemas/PlatformChatPersonSource" FILE: "#/components/schemas/PlatformChatFileSource" CUSTOM_ENTITY: "#/components/schemas/PlatformChatCustomEntitySource" PlatformChatCitationSnippet: type: object additionalProperties: false required: - text properties: text: type: string minLength: 1 page_number: type: - integer - "null" PlatformChatCitationAnnotation: type: object additionalProperties: false required: - type - sources properties: type: type: string enum: - CITATION sources: type: array minItems: 1 items: $ref: "#/components/schemas/PlatformChatCitationSource" start_index: type: - integer - "null" minimum: 0 end_index: type: - integer - "null" minimum: 0 snippets: type: - array - "null" items: $ref: "#/components/schemas/PlatformChatCitationSnippet" PlatformMessageTextBlock: type: object required: - text - type properties: text: type: string description: Text content. type: $ref: "#/components/schemas/PlatformContentType" annotations: type: array readOnly: true items: $ref: "#/components/schemas/PlatformChatCitationAnnotation" PlatformMessage: type: object required: - role - content properties: role: $ref: "#/components/schemas/PlatformMessageRole" content: type: array minItems: 1 description: Content blocks in the message. items: $ref: "#/components/schemas/PlatformMessageTextBlock" PlatformAgentRunCreateRequest: type: object additionalProperties: false description: | Request to run an agent. A request MUST supply either `messages` (a non-empty conversation) or `input` (for input-form triggered agents). example: messages: - role: USER content: - text: What is our parental leave policy? type: text properties: input: type: object description: Input fields for an input-form triggered agent. additionalProperties: true messages: type: array minItems: 1 description: | Messages to pass to the agent. When provided, the array MUST contain at least one message and each message MUST specify a valid `role` and non-empty `content`. items: $ref: "#/components/schemas/PlatformMessage" metadata: type: object description: Metadata to pass to the agent. additionalProperties: true stream: type: boolean description: Whether to stream the run response as server-sent events. Not supported in DURABLE mode. default: false execution_mode: type: string enum: - REQUEST_BOUND - DURABLE default: REQUEST_BOUND description: | REQUEST_BOUND preserves the existing wait/stream behavior. DURABLE starts a fresh, persisted execution with a 30-minute execution timeout and returns immediately. DURABLE requires stream to be false or omitted and does not accept metadata.chat_session_id. It does not bypass tool approval requirements or provide automatic QE-crash resumption. Expiry is read-triggered: the next GET of the run marks an active turn FAILED if more than 40 minutes have passed since the turn was accepted. There is no periodic sweep, so the stored run can remain RUNNING until it is read. Expiry never replays execution or expires approval-paused runs, and failure does not prove that external tool work has stopped. PlatformAgentRunCreate: type: object required: - agent_id properties: agent_id: type: string description: ID of the agent being run. input: type: object description: Input fields for an input-form triggered agent. additionalProperties: true messages: type: array description: Messages passed to the agent. items: $ref: "#/components/schemas/PlatformMessage" metadata: type: object description: Metadata passed to the agent. additionalProperties: true PlatformAgentExecutionStatus: type: string description: Status of the agent run. enum: - error - success PlatformAgentRun: allOf: - $ref: "#/components/schemas/PlatformAgentRunCreate" - type: object required: - status properties: status: $ref: "#/components/schemas/PlatformAgentExecutionStatus" PlatformAgentRunWaitResponse: type: object required: - request_id properties: run: $ref: "#/components/schemas/PlatformAgentRun" messages: type: array description: Messages returned by the completed run. items: $ref: "#/components/schemas/PlatformMessage" request_id: type: string description: Platform-generated request ID for support correlation. PlatformAgentRunState: type: string enum: - QUEUED - RUNNING - REQUIRES_INPUT - SUCCEEDED - FAILED - CANCELLING - CANCELLED - EXPIRED description: State of the persisted workflow execution. REQUIRES_INPUT is nonterminal. PlatformAgentRunToolApproval: type: object description: Pending approval for a specific persisted tool invocation and its arguments. required: - interaction_id - type - display_name - description - arguments properties: interaction_id: type: string description: Identifies this specific invocation approval, not the tool definition. type: type: string enum: - TOOL_APPROVAL description: Interaction type identifying a tool execution approval request. tool_id: type: string description: Platform tool identifier when recorded. Omitted for requests without one, such as some MCP tools. display_name: type: string description: Display name of the tool requesting approval. description: type: string description: Description of the tool associated with this approval request. arguments: type: object additionalProperties: true description: Arguments from the persisted approval request. Older platform tools use flattened parameters. expires_at: type: string format: date-time description: Approval deadline, when one is set. Omitted when the approval has no expiration. PlatformAgentRunError: type: object description: Caller-safe details of an agent run execution failure. required: - code - message properties: code: type: string description: Machine-readable execution failure code. message: type: string description: Caller-safe execution failure description. PlatformDurableAgentRun: type: object description: Agent run state, pending tool approvals, and output available independently of the creation request. required: - run_id - agent_id - state - created_at - updated_at - pending_interactions properties: run_id: type: string description: ID of the run, preserved across approval continuations. agent_id: type: string description: ID of the agent that owns the run. state: $ref: "#/components/schemas/PlatformAgentRunState" description: Current lifecycle state of the run. created_at: type: string format: date-time description: Timestamp when the run was first persisted. updated_at: type: string format: date-time description: | Latest persisted activity timestamp across the execution and its messages, including checkpoint messages. This is not a worker heartbeat or an exact state-transition timestamp. expires_at: type: string format: date-time description: Execution deadline, when one is set. Not the run history retention deadline. pending_interactions: type: array description: Unanswered tool approvals when the run is in REQUIRES_INPUT. Empty in other states. items: $ref: "#/components/schemas/PlatformAgentRunToolApproval" output: type: object additionalProperties: true description: Accumulated text-only agent output under the messages key, when available. error: $ref: "#/components/schemas/PlatformAgentRunError" description: Caller-safe failure details when the run is in FAILED. PlatformAgentRunResponse: type: object description: Persisted agent run snapshot with a request ID for support correlation. required: - run - request_id properties: run: $ref: "#/components/schemas/PlatformDurableAgentRun" description: Current persisted snapshot of the requested agent run. request_id: type: string description: Platform-generated request ID for support correlation. PlatformAuthenticationSuggestion: type: object description: One tool the caller must authorize before the agent can run. required: - server_id properties: tool_name: type: string description: Human-readable tool name. server_id: type: string description: Identifier to POST to `/tool-servers/{serverId}/auth` (Client API) with `returnUrl` in the request body to obtain an `authorizationUrl` to redirect the end user to. PlatformUnauthorizedAgentToolsProblem: description: Problem detail extended with `authentication_suggestions` naming each tool the caller must authorize. allOf: - $ref: "#/components/schemas/PlatformProblemDetail" - type: object required: - authentication_suggestions properties: authentication_suggestions: type: array description: One entry per tool the caller must authorize. items: $ref: "#/components/schemas/PlatformAuthenticationSuggestion" PlatformAgentRunCancellationRequest: type: object additionalProperties: false description: Request cooperative cancellation of a run owned by the caller. required: - run_id example: run_id: "{run_id}" properties: run_id: type: string minLength: 1 maxLength: 256 description: ID of the run to cancel. Must belong to the agent identified in the path. PlatformAgentRunApprovalDecision: type: object additionalProperties: false description: Approve or reject the invocation identified by a pending interaction ID. required: - interaction_id - decision properties: interaction_id: type: string minLength: 1 maxLength: 256 description: The interaction_id returned in the run's pending_interactions. decision: type: string enum: - APPROVE - REJECT description: The decision for this invocation only. Rejection follows normal workflow behavior. PlatformAgentRunResponsesRequest: type: object additionalProperties: false description: Invocation-scoped decisions for the complete pending approval batch. required: - run_id - responses example: run_id: "{run_id}" responses: - interaction_id: "{interaction_id}" decision: APPROVE properties: run_id: type: string minLength: 1 maxLength: 256 description: ID of the run whose pending approvals are being answered. Must belong to the agent identified in the path. responses: type: array minItems: 1 maxItems: 100 description: One decision per pending interaction. Interaction IDs must be unique. items: $ref: "#/components/schemas/PlatformAgentRunApprovalDecision" PlatformChatInputMessage: type: object additionalProperties: false required: - role - content properties: role: type: string enum: - USER - ASSISTANT content: type: string minLength: 1 PlatformChatTextFormat: type: object additionalProperties: false description: Unconstrained plain-text assistant output. required: - type properties: type: type: string description: Discriminator. Must be TEXT. enum: - TEXT PlatformChatJsonSchemaFormat: type: object additionalProperties: false description: Constrains the assistant response to a caller-supplied JSON Schema. required: - type - name - schema properties: type: type: string description: Discriminator. Must be JSON_SCHEMA. enum: - JSON_SCHEMA name: type: string minLength: 1 maxLength: 64 description: A stable identifier for the schema. description: type: string maxLength: 1024 description: An optional human-readable description of the schema. schema: type: object additionalProperties: true description: A JSON Schema object describing the desired output shape. strict: type: boolean default: true description: | When true, the provider validates the response against the schema. Unsupported by some providers; defaults to true. PlatformChatCreateRequest: type: object additionalProperties: false required: - input example: input: Summarize our parental leave policy as JSON. text: format: type: JSON_SCHEMA name: policy_summary schema: type: object properties: eligible_employees: type: string duration_weeks: type: integer required: - eligible_employees - duration_weeks strict: true properties: input: description: | Either a plain string (single user turn) or a chronological array of `USER`/`ASSISTANT` messages. The final array message must be `USER`. oneOf: - type: string minLength: 1 - type: array minItems: 1 items: $ref: "#/components/schemas/PlatformChatInputMessage" stream: type: boolean description: | When true, the HTTP response is `text/event-stream`. When false or omitted, the HTTP response is `application/json`. default: false store: type: boolean description: | When true (default), persist the interaction and return a `conversation_id`. When false, run ephemerally with no persistence. default: true conversation_id: type: string minLength: 1 description: | Continue an existing stored conversation. Incompatible with message-array `input` and with `store: false`. text: type: object additionalProperties: false description: | Optional configuration for the assistant's text response. When `format.type` is `JSON_SCHEMA`, the response is constrained to the supplied JSON schema and returned in `output[*].content[*].structured_output`. Structured output is not supported when `stream` is true. properties: format: description: | Output format for the assistant text. TEXT is unconstrained. JSON_SCHEMA constrains the response to the supplied schema. oneOf: - $ref: "#/components/schemas/PlatformChatTextFormat" - $ref: "#/components/schemas/PlatformChatJsonSchemaFormat" PlatformChatStreamResponseId: type: string minLength: 1 pattern: ^resp_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ description: | Platform-owned, non-persisted response envelope identifier in `resp_` form. The same identifier is used for every event in one streamed response. PlatformChatOutputTextContent: type: object additionalProperties: false required: - type - text properties: type: type: string enum: - OUTPUT_TEXT text: type: string structured_output: type: - object - "null" description: | Parsed and validated JSON object when structured output was requested. Present only when the request included `text.format.type: JSON_SCHEMA`. annotations: type: array items: $ref: "#/components/schemas/PlatformChatCitationAnnotation" PlatformChatOutputMessage: type: object additionalProperties: false required: - type - role - content properties: type: type: string enum: - MESSAGE role: type: string enum: - ASSISTANT content: type: array minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/PlatformChatOutputTextContent" PlatformChatCompletedResponse: type: object additionalProperties: false required: - id - object - created_at - status - output - store - request_id properties: id: $ref: "#/components/schemas/PlatformChatStreamResponseId" object: type: string enum: - RESPONSE created_at: type: string format: date-time description: RFC 3339 UTC timestamp when the response was created. status: type: string enum: - COMPLETED output: type: array minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/PlatformChatOutputMessage" store: type: boolean conversation_id: type: - string - "null" minLength: 1 description: Present when the interaction was persisted. request_id: type: string minLength: 1 PlatformChatStreamResponseCreated: type: object additionalProperties: false required: - type - response_id properties: type: type: string enum: - RESPONSE_CREATED response_id: $ref: "#/components/schemas/PlatformChatStreamResponseId" PlatformChatStreamProgress: type: object additionalProperties: false required: - type - response_id - text properties: type: type: string enum: - RESPONSE_PROGRESS response_id: $ref: "#/components/schemas/PlatformChatStreamResponseId" text: type: string minLength: 1 description: | Verbatim concatenated fragment text from an assistant UPDATE wire message. Display-oriented passthrough only; not part of the final answer and not present on terminal response snapshots. PlatformChatStreamOutputTextDelta: type: object additionalProperties: false required: - type - response_id - delta properties: type: type: string enum: - RESPONSE_OUTPUT_TEXT_DELTA response_id: $ref: "#/components/schemas/PlatformChatStreamResponseId" delta: type: string PlatformChatStreamOutputTextDone: type: object additionalProperties: false required: - type - response_id - text properties: type: type: string enum: - RESPONSE_OUTPUT_TEXT_DONE response_id: $ref: "#/components/schemas/PlatformChatStreamResponseId" text: type: string PlatformChatStreamResponseCompleted: type: object additionalProperties: false required: - type - response_id - response properties: type: type: string enum: - RESPONSE_COMPLETED response_id: $ref: "#/components/schemas/PlatformChatStreamResponseId" response: $ref: "#/components/schemas/PlatformChatCompletedResponse" PlatformChatResponseError: type: object additionalProperties: false required: - message properties: code: type: - string - "null" description: | Open snake_case error code aligned with ProblemDetail codes when present. Clients must tolerate unknown values; the set of codes is not a closed enum. Limit failures use `spend_limit_exceeded` (billing spend limit) and `token_limit_exceeded` (model context/token limit). example: spend_limit_exceeded message: type: string minLength: 1 PlatformChatFailedResponse: type: object additionalProperties: false required: - id - object - created_at - status - output - store - request_id - error properties: id: $ref: "#/components/schemas/PlatformChatStreamResponseId" object: type: string enum: - RESPONSE created_at: type: string format: date-time description: RFC 3339 UTC timestamp when the response was created. status: type: string enum: - FAILED output: type: array maxItems: 1 items: $ref: "#/components/schemas/PlatformChatOutputMessage" store: type: boolean conversation_id: type: - string - "null" minLength: 1 description: Present when the interaction was persisted. request_id: type: string minLength: 1 error: $ref: "#/components/schemas/PlatformChatResponseError" PlatformChatStreamResponseFailed: type: object additionalProperties: false required: - type - response_id - response properties: type: type: string enum: - RESPONSE_FAILED response_id: $ref: "#/components/schemas/PlatformChatStreamResponseId" response: $ref: "#/components/schemas/PlatformChatFailedResponse" PlatformChatStreamEvent: description: | JSON object written to the SSE `data` field. This schema is the payload for SDK transform, not the raw HTTP body. Do not run JSON response conformance on stream bodies. A typical wire frame is: id: 1 event: RESPONSE_CREATED data: {"type":"RESPONSE_CREATED","response_id":"resp_e65a0a77-97a2-4c91-be60-eae7f6238015"} example: type: RESPONSE_CREATED response_id: resp_e65a0a77-97a2-4c91-be60-eae7f6238015 oneOf: - $ref: "#/components/schemas/PlatformChatStreamResponseCreated" - $ref: "#/components/schemas/PlatformChatStreamProgress" - $ref: "#/components/schemas/PlatformChatStreamOutputTextDelta" - $ref: "#/components/schemas/PlatformChatStreamOutputTextDone" - $ref: "#/components/schemas/PlatformChatStreamResponseCompleted" - $ref: "#/components/schemas/PlatformChatStreamResponseFailed" discriminator: propertyName: type mapping: RESPONSE_CREATED: "#/components/schemas/PlatformChatStreamResponseCreated" RESPONSE_PROGRESS: "#/components/schemas/PlatformChatStreamProgress" RESPONSE_OUTPUT_TEXT_DELTA: "#/components/schemas/PlatformChatStreamOutputTextDelta" RESPONSE_OUTPUT_TEXT_DONE: "#/components/schemas/PlatformChatStreamOutputTextDone" RESPONSE_COMPLETED: "#/components/schemas/PlatformChatStreamResponseCompleted" RESPONSE_FAILED: "#/components/schemas/PlatformChatStreamResponseFailed" PlatformSkillStatus: type: string enum: - DRAFT - ENABLED - DISABLED description: | The caller's effective activation. The owner sees the skill's stored status. Another caller sees their personal setting, or DISABLED when they have none. DRAFT is the stored draft state and is not set by update. Effective activation may also reflect workspace governance policy. PlatformSkillOrigin: type: string enum: - CUSTOM - GITHUB description: Source category for the skill. PlatformSkillSyncStatus: type: string enum: - UP_TO_DATE - UPDATE_AVAILABLE - SYNC_FAILED description: Current external-source sync status. PlatformSkillSourceProvenance: type: object properties: source_url: type: string description: URL of the external source the skill was imported from. commit_sha: type: string description: Source commit SHA for the imported skill. imported_at: type: string format: date-time description: Time the skill was imported. last_synced_at: type: string format: date-time description: Time the skill was last synced from its source. sync_status: $ref: "#/components/schemas/PlatformSkillSyncStatus" sync_error: type: string description: Human-readable sync failure reason, present only when sync_status is SYNC_FAILED. PlatformPersonReference: type: object description: A lightweight reference to a person, used where a payload merely points at someone. required: - name properties: id: type: string description: Opaque Glean person ID. name: type: string description: Display name. PlatformSkill: type: object required: - skill_id - display_name - description - latest_version - latest_minor_version - status - origin - owner - created_at - updated_at properties: skill_id: type: string description: Glean skill ID. display_name: type: string description: Human-readable skill name. description: type: string description: Human-readable skill description. latest_version: type: integer description: Latest major version number for the skill. latest_minor_version: type: integer description: Latest minor version number for the skill. status: $ref: "#/components/schemas/PlatformSkillStatus" origin: $ref: "#/components/schemas/PlatformSkillOrigin" source_provenance: $ref: "#/components/schemas/PlatformSkillSourceProvenance" owner: $ref: "#/components/schemas/PlatformPersonReference" created_at: type: string format: date-time description: Time the skill was created. updated_at: type: string format: date-time description: Time the skill was last updated. PlatformSkillsListResponse: type: object required: - results - has_more - next_cursor - request_id properties: results: type: array description: Skills available to the user. items: $ref: "#/components/schemas/PlatformSkill" has_more: type: boolean description: Whether additional results are available. next_cursor: type: - string - "null" description: Cursor for the next page, or null when no more results are available. request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillCreateRequest: type: object additionalProperties: false required: - file properties: file: type: string format: binary description: SKILL.md, .zip, or .skill bundle to create. PlatformSkillCreateResponse: type: object required: - skill - request_id properties: skill: $ref: "#/components/schemas/PlatformSkill" request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillImportRequest: type: object additionalProperties: false required: - source_urls example: source_urls: - https://github.com/anthropics/skills/tree/main/skills/skill-creator properties: source_urls: type: array minItems: 1 maxItems: 100 uniqueItems: true description: Resolved GitHub skill URLs selected from a source preview. items: type: string minLength: 1 maxLength: 2048 PlatformSkillImportResponse: type: object required: - skills - request_id properties: skills: type: array minItems: 1 description: | Imported skills in request order. The import is atomic: either every source persists or none does. items: $ref: "#/components/schemas/PlatformSkill" request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillValidationRequest: type: object additionalProperties: false required: - file properties: file: type: string format: binary description: SKILL.md, .zip, or .skill bundle to validate. PlatformSkillValidationMetadata: type: object required: - display_name - description properties: display_name: type: string description: Skill name parsed from SKILL.md frontmatter. description: type: string description: Skill description parsed from SKILL.md frontmatter. PlatformSkillValidationFile: type: object required: - path - size_bytes - is_manifest properties: path: type: string description: Normalized relative path in the skill bundle. size_bytes: type: integer description: File size in bytes. is_manifest: type: boolean description: Whether this file is the skill manifest. PlatformSkillValidationResponse: type: object required: - metadata - files - warnings - request_id properties: metadata: $ref: "#/components/schemas/PlatformSkillValidationMetadata" files: type: array description: Normalized files in the bundle after stripping an optional single root folder. items: $ref: "#/components/schemas/PlatformSkillValidationFile" warnings: type: array description: Non-blocking validation warnings. items: $ref: "#/components/schemas/PlatformWarning" request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillSourcePreviewRequest: type: object additionalProperties: false required: - source_url example: source_url: https://github.com/anthropics/skills properties: source_url: type: string minLength: 1 maxLength: 2048 description: GitHub URL for a skill directory, SKILL.md file, or repository to inspect. stream: type: boolean default: false description: Whether to stream repository scan progress using server-sent events. PlatformSkillSourcePreviewFile: type: object required: - path - content properties: path: type: string description: Relative path within the skill bundle. content: type: string description: UTF-8 file content. PlatformSkillSourcePreview: type: object required: - display_name - description - source_url - commit_sha - main_content - files - file_tree properties: display_name: type: string description: Skill name parsed from SKILL.md frontmatter. description: type: string description: Skill description parsed from SKILL.md frontmatter. source_url: type: string description: Resolved URL for this skill within the source. commit_sha: type: string description: Commit SHA used to produce the preview. main_content: type: string description: SKILL.md content fetched as part of the preview. files: type: array description: Supporting files fetched with the skill. items: $ref: "#/components/schemas/PlatformSkillSourcePreviewFile" file_tree: type: array description: Relative paths discovered for the skill. items: type: string PlatformSkillSourcePreviewFailureCode: type: string enum: - INVALID_SKILL - SKILL_FETCH_FAILED description: Stable machine-readable reason a discovered entry was excluded. PlatformSkillSourcePreviewFailure: type: object required: - source_url - code - detail properties: source_url: type: string description: Resolved URL for the entry that could not be previewed. code: $ref: "#/components/schemas/PlatformSkillSourcePreviewFailureCode" detail: type: string description: Safe explanation of why the entry was excluded. PlatformSkillSourcePreviewResponse: type: object required: - skills - failures - request_id properties: skills: type: array minItems: 1 description: Valid skills discovered at the source URL. items: $ref: "#/components/schemas/PlatformSkillSourcePreview" failures: type: array description: Discovered entries that could not be included in the preview. items: $ref: "#/components/schemas/PlatformSkillSourcePreviewFailure" request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillSourcePreviewStreamScan: type: object additionalProperties: false description: Repository scan started; names every skill path found. required: - type - total - skill_paths properties: type: type: string enum: - SCAN description: Event type, also sent as the SSE `event` name. total: type: integer minimum: 0 description: Number of skill paths found in the scan. skill_paths: type: array description: Skill paths found in the scan. items: type: string description: One skill path found in the scan. PlatformSkillSourcePreviewStreamProgress: type: object additionalProperties: false description: One skill finished inspecting; names the skill in progress. required: - type - completed - total - current_skill properties: type: type: string enum: - PROGRESS description: Event type, also sent as the SSE `event` name. completed: type: integer minimum: 0 description: Number of skills inspected so far. total: type: integer minimum: 0 description: Number of skills to inspect. current_skill: type: string description: Path of the skill being inspected. PlatformSkillSourcePreviewStreamSkill: type: object additionalProperties: false description: One skill previewed; carries the previewed skill. required: - type - skill properties: type: type: string enum: - SKILL description: Event type, also sent as the SSE `event` name. skill: $ref: "#/components/schemas/PlatformSkillSourcePreview" description: The previewed skill. PlatformSkillSourcePreviewStreamResult: type: object additionalProperties: false description: Terminal success event carrying the fully assembled preview. required: - type - response properties: type: type: string enum: - RESULT description: Event type, also sent as the SSE `event` name. response: $ref: "#/components/schemas/PlatformSkillSourcePreviewResponse" description: The fully assembled preview response. PlatformSkillSourcePreviewStreamError: type: object additionalProperties: false description: Terminal failure event carrying the failure as a problem detail. Most GitHub authorization failures return HTTP 422 before the stream opens. If authorization fails after the stream opens, `error.code` is `tools_unauthorized` and `authentication_suggestions` is present. required: - type - error properties: type: type: string enum: - ERROR description: Event type, also sent as the SSE `event` name. error: $ref: "#/components/schemas/PlatformProblemDetail" description: The failure as a problem detail. authentication_suggestions: type: array minItems: 1 description: Present only when `error.code` is `tools_unauthorized`. Names the GitHub action pack to authorize, with the same retry flow as the 422 response. items: $ref: "#/components/schemas/PlatformAuthenticationSuggestion" PlatformSkillSourcePreviewStreamEvent: description: | JSON object written to the SSE `data` field of a streaming source preview. This schema is the payload for SDK transform, not the raw HTTP body. Do not run JSON response conformance on stream bodies. Each frame also carries an `event` name matching the payload `type`. The stream ends with the RESULT event on success or the ERROR event on failure. A typical wire frame is: event: SCAN data: {"type":"SCAN","total":1,"skill_paths":["https://github.com/acme/skills/tree/main/skills/example"]} example: type: SCAN total: 1 skill_paths: - https://github.com/acme/skills/tree/main/skills/example oneOf: - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamScan" - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamProgress" - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamSkill" - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamResult" - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamError" discriminator: propertyName: type mapping: SCAN: "#/components/schemas/PlatformSkillSourcePreviewStreamScan" PROGRESS: "#/components/schemas/PlatformSkillSourcePreviewStreamProgress" SKILL: "#/components/schemas/PlatformSkillSourcePreviewStreamSkill" RESULT: "#/components/schemas/PlatformSkillSourcePreviewStreamResult" ERROR: "#/components/schemas/PlatformSkillSourcePreviewStreamError" PlatformSkillGetResponse: type: object required: - skill - request_id properties: skill: $ref: "#/components/schemas/PlatformSkill" request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillUpdateStatus: type: string enum: - ENABLED - DISABLED description: | Activation to apply for the authenticated caller. For the owner, this updates the skill's stored status. For any other caller, it updates only that caller's setting. PlatformSkillUpdateRequest: type: object additionalProperties: false required: - status example: status: ENABLED properties: status: $ref: "#/components/schemas/PlatformSkillUpdateStatus" PlatformSkillUpdateResponse: type: object required: - skill - request_id properties: skill: $ref: "#/components/schemas/PlatformSkill" request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillSyncResponse: type: object required: - commit_sha - is_updated - request_id properties: commit_sha: type: string minLength: 1 description: Git commit SHA now associated with the skill. is_updated: type: boolean description: Whether this request created a new skill version. request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillVersion: type: object required: - skill_id - version - minor_version - is_latest - created_by - created_at - updated_at properties: skill_id: type: string description: Glean skill ID. version: type: integer description: Major version number. minor_version: type: integer description: Minor version number. is_latest: type: boolean description: Whether this is the latest version of the skill. created_by: $ref: "#/components/schemas/PlatformPersonReference" created_at: type: string format: date-time description: Time this version was created. updated_at: type: string format: date-time description: Time this version was last updated. source_provenance: $ref: "#/components/schemas/PlatformSkillSourceProvenance" PlatformSkillVersionsListResponse: type: object required: - results - has_more - next_cursor - request_id properties: results: type: array description: Versions available for the skill. items: $ref: "#/components/schemas/PlatformSkillVersion" has_more: type: boolean description: Whether additional results are available. next_cursor: type: - string - "null" description: Cursor for the next page, or null when no more results are available. request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillVersionCreateRequest: type: object additionalProperties: false required: - file properties: file: type: string format: binary description: SKILL.md, .zip, or .skill bundle to store as a new version. PlatformSkillVersionCreateResponse: type: object required: - version - request_id properties: version: $ref: "#/components/schemas/PlatformSkillVersion" request_id: type: string description: Platform-generated request ID for support correlation. PlatformSkillVersionGetResponse: type: object required: - version - request_id properties: version: $ref: "#/components/schemas/PlatformSkillVersion" request_id: type: string description: Platform-generated request ID for support correlation. PlatformFilterOperator: type: string description: Supported filter operator. enum: - EQUALS - NOT_EQUALS - GT - GTE - LT - LTE PlatformFilter: type: object additionalProperties: false required: - field - values description: | A single filter criterion. For `EQUALS`, multiple values within a filter are OR'd; for `NOT_EQUALS`, listed values are excluded. Separate filters are AND'd with each other and with inline operators in `query`. Repeated same-field `EQUALS` filters are rejected. properties: field: type: string minLength: 1 description: | Filter field name. Built-in names (case-sensitive, lowercase only): `type`, `owner`, `from`, `author`, `channel`, `status`, `assignee`, `reporter`, `component`, `mentions`, and `collection`. Built-ins accept only `EQUALS` and `NOT_EQUALS`. Any other nonblank name is accepted as a custom filter without spelling, existence, or type checks; behavior depends on your connected sources. example: type values: type: array minItems: 1 items: type: string minLength: 1 description: | One or more values to match. Prefer values returned by filter discovery unchanged. For people (`USER`) fields, values may be email addresses or display names. example: - spreadsheet - presentation operator: allOf: - $ref: "#/components/schemas/PlatformFilterOperator" description: | Comparison operator. Defaults to `EQUALS`. Built-in fields support only `EQUALS` and `NOT_EQUALS`. Range operators (`GT`, `GTE`, `LT`, `LTE`) require exactly one value; express ranges with multiple filters on the same field. Custom fields may support different operators depending on the data source. PlatformTimeRange: type: object additionalProperties: false description: Filter results to those last updated within this range. properties: start: type: string format: date-time description: Inclusive lower bound in ISO 8601 format. end: type: string format: date-time description: Exclusive upper bound in ISO 8601 format. PlatformSearchRequest: type: object additionalProperties: false required: - query example: query: quarterly planning 2026 properties: query: type: string minLength: 1 description: | The search query string. Supports inline operators such as `from:jane type:document app:confluence`. Inline operators are AND'd with structured `filters`. page_size: type: integer minimum: 1 maximum: 100 default: 10 description: Number of results to return per page. cursor: type: - string - "null" description: | Opaque pagination token from a previous response's `next_cursor` field. Omit on the first request. datasources: type: array minItems: 1 items: type: string minLength: 1 description: | Restrict results to specific datasource identifiers returned by `GET /api/search/filters`. Scopes by datasource type and may include results from multiple instances of that type. filters: type: array minItems: 1 items: $ref: "#/components/schemas/PlatformFilter" description: | Structured filters applied to search results. Multiple values within a filter with `EQUALS` are OR'd; separate filters are AND'd. Conflicting constraints on the same field (for example, `type:document` in `query` and `type:spreadsheet` in a filter) return an empty result set. See `Filter.field` for built-in field names and operators. Other nonblank field names are accepted as custom filters without validation; behavior depends on your connected sources. time_range: $ref: "#/components/schemas/PlatformTimeRange" PlatformResult: type: object additionalProperties: false required: - url - title - datasource properties: url: type: string format: uri minLength: 1 description: Canonical URL of the result. example: https://company.atlassian.net/wiki/spaces/ENG/pages/12345 title: type: string minLength: 1 description: Display title. For a conversation, this is a title built from the participants, such as "Alice and Bob", including when the indexed title is the message body. When the result has no title, the server returns Untitled. example: Q2 2026 Platform Roadmap snippets: type: array items: type: string minLength: 1 description: Query-relevant plain-text excerpts from the result body. example: - The platform team will focus on API stability and... datasource: type: string minLength: 1 description: The datasource this result originates from. example: confluence document_type: type: - string - "null" minLength: 1 description: The document type within the datasource. example: page creator: $ref: "#/components/schemas/PlatformPersonReference" owner: $ref: "#/components/schemas/PlatformPersonReference" updated_at: type: - string - "null" format: date-time description: When the result was last modified. created_at: type: - string - "null" format: date-time description: When the result was created. PlatformSearchResponse: type: object additionalProperties: false required: - results - has_more - next_cursor - request_id - warnings properties: results: type: array items: $ref: "#/components/schemas/PlatformResult" description: | Ordered list of ranked document results. People cards, Q&A blocks, and other UI-only result types are not included. has_more: type: boolean description: Indicates whether additional pages of results are available. next_cursor: type: - string - "null" description: Opaque token to pass as `cursor` in the next request. request_id: type: string minLength: 1 description: Platform-generated request ID for support correlation. warnings: type: array description: | Non-blocking warnings for this response. Required; use `[]` when there are none. Clients must tolerate unknown warning codes. `results_incomplete` means some results may be unavailable for the requested datasource scope while `results`, `has_more`, and `next_cursor` remain present. Warning messages are generic and do not include query text or internal identifiers. items: $ref: "#/components/schemas/PlatformWarning" PlatformFilterFieldInfo: type: object additionalProperties: false required: - field - type - operators properties: field: type: string minLength: 1 description: Field name usable in the `filters` array for `POST /api/search`. example: status type: type: string minLength: 1 description: | Open field-type string. Current values are `STRING` for text and keyword fields and `USER` for people fields (`owner`, `from`, `author`, `assignee`, `reporter`, `mentions`). Clients must tolerate unknown values. example: STRING operators: type: array minItems: 1 description: | Comparison operators supported for this field. Built-in fields expose `EQUALS` and `NOT_EQUALS`. items: $ref: "#/components/schemas/PlatformFilterOperator" values: type: array description: | Suggested filter values observed for the supplied `query`. Omitted in catalog-only responses. Present as an array, including `[]`, when `query` is provided. Values are a bounded, non-exhaustive sample in search-provider order and may include duplicates; blank values are omitted. No additional endpoint-specific truncation is applied. Grouping in the search UI is not preserved; each value applies to the field broadly. An empty array does not mean no valid value exists. Availability varies by data source; federated and MCP integrations may return page-derived values or none at all. Reusing a suggested value in `POST /api/search` does not guarantee matching results or identical filter behavior. For `USER` fields, values may be email addresses or display names. items: type: string minLength: 1 PlatformDatasourceFilterInfo: type: object additionalProperties: false required: - datasource - filters properties: datasource: type: string minLength: 1 description: | Datasource identifier usable in `POST /api/search` `datasources`. example: jira filters: type: array description: | Common built-in filter fields for this datasource. May be empty. A built-in omitted here can still be valid in `POST /api/search`; see `Filter.field` for the full built-in name list. items: $ref: "#/components/schemas/PlatformFilterFieldInfo" PlatformSearchFiltersResponse: type: object additionalProperties: false required: - datasources - request_id properties: datasources: type: array description: | Datasources visible to the authenticated user. Each `datasource` is an identifier you can pass to `POST /api/search` `datasources`. An empty array means no visible datasources. items: $ref: "#/components/schemas/PlatformDatasourceFilterInfo" request_id: type: string minLength: 1 description: Platform-generated request ID for support correlation. PlatformPerMemberSettings: type: object additionalProperties: false description: Resolution settings for the per-member limit family. required: - idp_groups properties: idp_groups: type: string enum: - HIGHEST - LOWEST description: | How to resolve effective usage limits when a user belongs to multiple IdP groups. PlatformMultipleMembershipResolutionSettings: type: object additionalProperties: false description: Settings for resolving limits across multiple memberships. required: - per_member properties: per_member: $ref: "#/components/schemas/PlatformPerMemberSettings" description: Resolution settings for the per-member limit family. PlatformLimitIncreaseRequestSettings: type: object additionalProperties: false description: | Settings that govern usage limit increase requests. required: - business_justification properties: business_justification: type: string enum: - OPTIONAL - REQUIRED description: | Whether a business justification is required when requesting a usage limit increase. PlatformUsageSettingsResource: type: object additionalProperties: false description: | Workspace-wide usage settings. properties: multiple_membership_resolution: $ref: "#/components/schemas/PlatformMultipleMembershipResolutionSettings" description: Settings for resolving limits across multiple memberships. limit_increase_requests: $ref: "#/components/schemas/PlatformLimitIncreaseRequestSettings" description: Settings that govern usage limit increase requests. updated_at: type: string format: date-time description: | ISO 8601 timestamp of the last settings update. PlatformUsageSettingsResponse: type: object additionalProperties: false description: | Response envelope for usage settings operations. required: - usage_settings - request_id properties: usage_settings: $ref: "#/components/schemas/PlatformUsageSettingsResource" description: Current workspace-wide usage settings. request_id: type: string description: | Opaque request identifier. PlatformUsageSettingsUpdateRequest: type: object additionalProperties: false description: | Request body for updating workspace-wide usage settings. required: [] anyOf: - required: - multiple_membership_resolution - required: - limit_increase_requests properties: multiple_membership_resolution: $ref: "#/components/schemas/PlatformMultipleMembershipResolutionSettings" description: Settings for resolving limits across multiple memberships. limit_increase_requests: $ref: "#/components/schemas/PlatformLimitIncreaseRequestSettings" description: Settings that govern usage limit increase requests. PlatformUsageTargetType: type: string description: Kind of governed population or inherited policy source. enum: - ORGANIZATION - DEFAULT_USER - DEFAULT_AGENT - USER - AGENT - IDP_GROUP - DEPARTMENT x-enumDescriptions: ORGANIZATION: Shared limit across the organization for the selected spend client. DEFAULT_USER: Default per-user limit for the selected spend client. DEFAULT_AGENT: Default aggregate limit applied to agents without an agent-specific limit. USER: Limit for one user, identified by canonical user ID or email, and the selected spend client. AGENT: Aggregate limit for one canonical agent ID, independent of spend client. IDP_GROUP: Response-only source of an inherited per-user IdP-group limit. DEPARTMENT: Response-only source of an inherited per-user department limit. x-speakeasy-enum-descriptions: ORGANIZATION: Shared limit across the organization for the selected spend client. DEFAULT_USER: Default per-user limit for the selected spend client. DEFAULT_AGENT: Default aggregate limit applied to agents without an agent-specific limit. USER: Limit for one user, identified by canonical user ID or email, and the selected spend client. AGENT: Aggregate limit for one canonical agent ID, independent of spend client. IDP_GROUP: Response-only source of an inherited per-user IdP-group limit. DEPARTMENT: Response-only source of an inherited per-user department limit. PlatformUsageTarget: type: object description: | Population governed by a usage limit. A target identifies policy, not access. Administrative operations require their dedicated scope and billing permissions. Non-admin evaluation accepts the authenticated USER or an AGENT the caller currently has permission to edit. Billing permission does not widen this route. Organization and user limits are scoped to a spend client; agent limits remain aggregate. Subagents cannot be configured or evaluated independently because nested spend can be attributed to the top-level agent. Reset can still remove existing subagent rules. A USER target is identified by user_id, email, or both; email is resolved to the canonical user_id, which responses always return. additionalProperties: false required: - type properties: type: $ref: "#/components/schemas/PlatformUsageTargetType" description: Kind of governed population. user_id: type: string minLength: 1 maxLength: 512 description: | Canonical user ID; valid only when type is USER. A USER target requires user_id, email, or both. email: type: string minLength: 3 maxLength: 320 pattern: ^[^\s@\x00-\x1f\x7f]+@[^\s@\x00-\x1f\x7f]+$ x-glean-experimental: id: 1e7ce9ed-56af-44b2-81c1-f39e656919ea introduced: "2026-09-29" description: | Email address of the user, including a known alias email; valid only when type is USER. Matching is case-insensitive and resolves to the canonical user_id. When user_id is also supplied, both must identify the same user. Email is never part of the stored limit key. Responses include the user's directory email when one is available. agent_id: type: string minLength: 1 maxLength: 512 description: Canonical agent ID; required only when type is AGENT. allOf: - oneOf: - anyOf: - required: - user_id - required: - email properties: type: description: Kind of governed population. enum: - USER not: required: - agent_id - required: - agent_id properties: type: description: Kind of governed population. enum: - AGENT not: anyOf: - required: - user_id - required: - email - properties: type: description: Kind of governed population. enum: - ORGANIZATION - DEFAULT_USER - DEFAULT_AGENT not: anyOf: - required: - user_id - required: - email - required: - agent_id PlatformPeriodType: type: string description: Kind of period over which usage is counted. enum: - RECURRING_CALENDAR_MONTH x-enumDescriptions: RECURRING_CALENDAR_MONTH: Resets at the start of each calendar month. x-speakeasy-enum-descriptions: RECURRING_CALENDAR_MONTH: Resets at the start of each calendar month. PlatformPeriod: type: object description: Period over which usage is counted for a limit. additionalProperties: false required: - type properties: type: $ref: "#/components/schemas/PlatformPeriodType" description: Kind of usage period. PlatformUsageSelector: type: object description: | Usage counted against a configured limit, or the spend context for evaluation. Configured organization and user limits require a client; aggregate agent limits omit it. Omission never selects Glean or acts as a client wildcard. additionalProperties: false required: - period properties: client_id: type: string x-glean-experimental: id: 3a8dfb97-fbe9-4173-ac61-4fd6e6faa847 introduced: "2026-09-23" minLength: 1 maxLength: 256 pattern: ^[^\x00-\x1f\x7f]+$ not: anyOf: - enum: - __deleted_clients__ - pattern: "^[ \\t-\\r\N\_  - \L\P  　]*$" description: | Opaque, case-sensitive spend-client ID, such as glean or an external gateway spend-client ID. Case and leading or trailing padding are preserved exactly; this is not inferred from the authenticating OAuth application, prefixed, or normalized. Empty and whitespace-only IDs (including Unicode whitespace), synthetic UI aggregation IDs, and control characters are invalid. Unknown IDs are valid and can have no applicable configured policies. period: $ref: "#/components/schemas/PlatformPeriod" description: Reset cadence for counted usage. PlatformAllocationMode: type: string description: How a usage limit budget is shared across the target population. enum: - SHARED_POOL - PER_MEMBER x-enumDescriptions: SHARED_POOL: A single shared budget for the target population. PER_MEMBER: A separate budget for each member of the target population. x-speakeasy-enum-descriptions: SHARED_POOL: A single shared budget for the target population. PER_MEMBER: A separate budget for each member of the target population. PlatformAmountMode: type: string description: Kind of configured cap or remaining headroom. enum: - FINITE - UNLIMITED x-enumDescriptions: FINITE: A finite value; amount is required for a configured cap and remaining for headroom. UNLIMITED: No cap or finite headroom. x-speakeasy-enum-descriptions: FINITE: A finite value; amount is required for a configured cap and remaining for headroom. UNLIMITED: No cap or finite headroom. PlatformUsageUnit: type: string description: Unit used by a usage limit and its counters. enum: - USD - CREDITS x-enumDescriptions: USD: United States dollars. CREDITS: Glean usage credits. x-speakeasy-enum-descriptions: USD: United States dollars. CREDITS: Glean usage credits. PlatformEnforcement: type: string description: Enforcement behavior when a usage limit is reached. enum: - HARD - SOFT x-enumDescriptions: HARD: Configured hard cap; when enforced, requests are blocked at the limit. SOFT: Configured soft cap; when enforced, requests are allowed but flagged at the limit. x-speakeasy-enum-descriptions: HARD: Configured hard cap; when enforced, requests are blocked at the limit. SOFT: Configured soft cap; when enforced, requests are allowed but flagged at the limit. PlatformUsageLimitValue: type: object description: Value and enforcement configuration for a usage limit. additionalProperties: false required: - mode properties: mode: $ref: "#/components/schemas/PlatformAmountMode" description: Whether the limit has a finite cap or is unlimited. amount: type: string minLength: 1 maxLength: 24 pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$ description: | Plain non-negative decimal amount with at most six fractional digits; required when mode is FINITE and forbidden when mode is UNLIMITED. Limits use single-precision (float32) storage: inputs are rounded to that precision, and responses report the stored value rounded to six fractional digits. For example, 100.10 can be returned as 100.099998. This storage limitation does not reduce the precision of measured usage counters. unit: $ref: "#/components/schemas/PlatformUsageUnit" description: | Unit for the selected spend domain; must match its billing denomination. Aggregate agent limits use the workspace plan denomination. enforcement: $ref: "#/components/schemas/PlatformEnforcement" description: How the limit is enforced when reached. allOf: - oneOf: - required: - amount - unit - enforcement properties: mode: description: Whether the limit has a finite cap or is unlimited. enum: - FINITE - properties: mode: description: Whether the limit has a finite cap or is unlimited. enum: - UNLIMITED not: anyOf: - required: - amount - required: - unit - required: - enforcement PlatformUsageLimit: type: object description: A configured usage limit and its value. additionalProperties: false required: - target - usage_selector - value properties: target: $ref: "#/components/schemas/PlatformUsageTarget" description: Population governed by this limit. usage_selector: $ref: "#/components/schemas/PlatformUsageSelector" description: Usage counted against this limit. allocation_mode: $ref: "#/components/schemas/PlatformAllocationMode" description: | Required for ORGANIZATION, DEFAULT_USER, and DEFAULT_AGENT. Must not be provided for USER or AGENT targets. value: $ref: "#/components/schemas/PlatformUsageLimitValue" description: Value, unit, and enforcement mode for the limit. allOf: - oneOf: - required: - allocation_mode properties: target: description: Population governed by this limit. properties: type: description: Kind of governed population. enum: - ORGANIZATION allocation_mode: description: How this limit budget is allocated. enum: - SHARED_POOL - required: - allocation_mode properties: target: description: Population governed by this limit. properties: type: description: Kind of governed population. enum: - DEFAULT_USER - DEFAULT_AGENT allocation_mode: description: How this limit budget is allocated. enum: - PER_MEMBER - properties: target: description: Population governed by this limit. properties: type: description: Kind of governed population. enum: - USER - AGENT not: required: - allocation_mode - oneOf: - properties: target: description: Population governed by this client-scoped limit. properties: type: description: Kind of client-scoped population. enum: - ORGANIZATION - DEFAULT_USER - USER usage_selector: description: Spend client and period for this limit. required: - client_id - properties: target: description: Population governed by this aggregate agent limit. properties: type: description: Kind of aggregate agent population. enum: - DEFAULT_AGENT - AGENT usage_selector: description: Aggregate period without a client partition. not: required: - client_id PlatformListUsageLimitsResponse: type: object description: Response body for listing configured usage limits. additionalProperties: false required: - results - has_more - request_id properties: results: type: array description: | Up to page_size matching configured limits. The service scans past omitted rules to fill the page unless the collection is exhausted. Continue with next_cursor and the same filters while has_more is true. items: $ref: "#/components/schemas/PlatformUsageLimit" has_more: type: boolean description: Whether more rules remain to scan; later pages may contain no matching results. next_cursor: type: - string - "null" description: Opaque cursor; null or absent when has_more is false. request_id: type: string description: Request identifier for correlating this response. PlatformUpsertUsageLimitResponse: type: object description: Response envelope for an upserted usage limit. additionalProperties: false required: - usage_limit - request_id properties: usage_limit: $ref: "#/components/schemas/PlatformUsageLimit" description: The normalized usage limit. request_id: type: string description: Request identifier for correlating this response. PlatformUsageLimitKey: type: object description: Natural key for one configured usage limit. additionalProperties: false required: - target - usage_selector properties: target: $ref: "#/components/schemas/PlatformUsageTarget" description: Population governed by the limit. usage_selector: $ref: "#/components/schemas/PlatformUsageSelector" description: Usage counted against the limit. allOf: - oneOf: - properties: target: description: Population governed by this client-scoped limit. properties: type: description: Kind of client-scoped population. enum: - ORGANIZATION - DEFAULT_USER - USER usage_selector: description: Spend client and period for this limit. required: - client_id - properties: target: description: Population governed by this aggregate agent limit. properties: type: description: Kind of aggregate agent population. enum: - DEFAULT_AGENT - AGENT usage_selector: description: Aggregate period without a client partition. not: required: - client_id PlatformResetUsageLimitsResponse: type: object description: Response body for resetting a usage limit. additionalProperties: false required: - is_configuration_removed - request_id properties: is_configuration_removed: type: boolean description: Whether the matching usage limit configuration was removed. request_id: type: string description: Request identifier for correlating this response. PlatformBatchUsageLimitsResponse: type: object additionalProperties: false description: Response body for successfully applied usage limit policies. required: - results - request_id properties: results: type: array items: $ref: "#/components/schemas/PlatformUsageLimit" description: Applied usage limit policies, in the same order as the request. request_id: type: string description: Request identifier for correlating this response. PlatformEvaluateUsageLimitRequest: type: object additionalProperties: false description: | Administrative evaluation request. The target is always explicit; usage_selector and the evaluation response are shared with non-admin evaluation. required: - target - usage_selector properties: target: $ref: "#/components/schemas/PlatformUsageTarget" description: Concrete organization, user, or agent to evaluate. usage_selector: $ref: "#/components/schemas/PlatformUsageSelector" description: Usage to evaluate for the target. allOf: - properties: usage_selector: description: Explicit spend-client context for evaluation. required: - client_id target: description: Concrete target being evaluated. properties: type: description: Kind of target being evaluated. enum: - ORGANIZATION - USER - AGENT PlatformUsageLimitDecision: type: string description: Configured-budget status for the target, independent of runtime admission switches. enum: - AVAILABLE - WARNING - BLOCKED x-enumDescriptions: AVAILABLE: Usage is within all applicable configured limits. WARNING: Usage reached or exceeded a configured soft limit. BLOCKED: Usage reached or exceeded a configured hard limit; this is not a runtime admission decision. x-speakeasy-enum-descriptions: AVAILABLE: Usage is within all applicable configured limits. WARNING: Usage reached or exceeded a configured soft limit. BLOCKED: Usage reached or exceeded a configured hard limit; this is not a runtime admission decision. PlatformUsageHeadroomValue: type: object description: Remaining configured budget in one unit, not a configured cap or runtime admission result. additionalProperties: false required: - mode properties: mode: $ref: "#/components/schemas/PlatformAmountMode" description: Whether remaining headroom is finite or unlimited. remaining: type: string minLength: 1 maxLength: 24 pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$ description: | Non-negative decimal headroom after accrued usage and approved one-period grants, clamped to zero when the configured limit is reached or exceeded. Required for FINITE; forbidden for UNLIMITED. unit: $ref: "#/components/schemas/PlatformUsageUnit" description: Unit of finite headroom; omitted for unlimited headroom. enforcement: $ref: "#/components/schemas/PlatformEnforcement" description: Enforcement configuration of the tightest finite policy; omitted for unlimited headroom. allOf: - oneOf: - required: - remaining - unit - enforcement properties: mode: description: Finite remaining headroom. enum: - FINITE remaining: type: string description: Remaining configured budget in decimal units. - properties: mode: description: Unlimited remaining headroom. enum: - UNLIMITED not: anyOf: - required: - remaining properties: remaining: description: Forbidden for unlimited headroom. - required: - unit properties: unit: description: Forbidden for unlimited headroom. - required: - enforcement properties: enforcement: description: Forbidden for unlimited headroom. PlatformUsagePolicySourceTarget: type: object description: | Population that supplied an evaluated policy. IdP groups and departments are response-only sources, not limit-management or direct evaluation targets. additionalProperties: false required: - type properties: type: $ref: "#/components/schemas/PlatformUsageTargetType" description: Kind of configured policy source. user_id: type: string minLength: 1 description: Canonical user ID for a user-specific policy. email: type: string minLength: 1 x-glean-experimental: id: 618d5192-fb51-451f-ba79-51304a408b55 introduced: "2026-09-29" description: | Directory email of the user for a user-specific policy; omitted when the directory has no email for the user. agent_id: type: string minLength: 1 description: Canonical agent ID for an agent-specific policy. group_id: type: string minLength: 1 description: Canonical IdP group ID; returned only to billing readers. department_name: type: string minLength: 1 description: Department whose per-user policy supplied the limit. is_identity_restricted: type: boolean description: True when an IdP-group source identity is withheld from a non-billing reader. allOf: - oneOf: - properties: type: description: Organization or inherited default policy. enum: - ORGANIZATION - DEFAULT_USER - DEFAULT_AGENT not: anyOf: - required: - user_id - required: - email - required: - agent_id - required: - group_id - required: - department_name - required: - is_identity_restricted - required: - user_id properties: type: description: User-specific policy. enum: - USER not: anyOf: - required: - agent_id - required: - group_id - required: - department_name - required: - is_identity_restricted - required: - agent_id properties: type: description: Agent-specific policy. enum: - AGENT not: anyOf: - required: - user_id - required: - email - required: - group_id - required: - department_name - required: - is_identity_restricted - required: - department_name properties: type: description: Inherited department policy. enum: - DEPARTMENT not: anyOf: - required: - user_id - required: - email - required: - agent_id - required: - group_id - required: - is_identity_restricted - properties: type: description: Inherited IdP-group policy. enum: - IDP_GROUP not: anyOf: - required: - user_id - required: - email - required: - agent_id - required: - department_name oneOf: - required: - group_id properties: is_identity_restricted: description: An identified group is not restricted. const: false - required: - is_identity_restricted properties: is_identity_restricted: description: An unidentified group has a restricted identity. const: true not: required: - group_id PlatformEvaluatedLimit: type: object additionalProperties: false description: Evaluation details for one independently applicable usage limit. required: - target - usage_selector - value - used - decision properties: target: $ref: "#/components/schemas/PlatformUsagePolicySourceTarget" description: | Configured source of this limit. Default and group policies retain their source population; used is the concrete evaluated user's or agent's counter. IdP-group identities require billing-read permission, but all callers receive the complete limit value, counter, decision, and headroom. usage_selector: $ref: "#/components/schemas/PlatformUsageSelector" description: | Actual scope of this rule's counter. Client rules identify their client; aggregate agent rules omit client_id even when evaluation selects a client. value: $ref: "#/components/schemas/PlatformUsageLimitValue" description: Configured cap before approved one-period grants; value.amount is not remaining headroom. used: type: string description: Decimal amount of accrued usage for this limit. decision: $ref: "#/components/schemas/PlatformUsageLimitDecision" description: Decision for this limit. PlatformEvaluateUsageLimitResponse: type: object additionalProperties: false description: | Configured-budget evaluation for a concrete target and selector, not runtime admission, model eligibility, or agent-run preflight. AVAILABLE can mean that no configured policy applies; inspect applicable_policy_count and the exact selector echo. Configured caps are evaluated_limits[].value.amount, accrued usage is evaluated_limits[].used, and remaining budget is effective_limits[].remaining. Approved one-period grants raise headroom without changing the configured cap. Units are never combined or converted. example: target: type: USER user_id: user-123 usage_selector: client_id: glean period: type: RECURRING_CALENDAR_MONTH applicable_policy_count: 1 decision: AVAILABLE effective_limits: - mode: FINITE remaining: "60" unit: USD enforcement: HARD evaluated_limits: - target: type: DEFAULT_USER usage_selector: client_id: glean period: type: RECURRING_CALENDAR_MONTH value: mode: FINITE amount: "80" unit: USD enforcement: HARD used: "20" decision: AVAILABLE evaluated_at: "2026-10-06T18:48:16Z" request_id: example-request required: - target - usage_selector - applicable_policy_count - decision - effective_limits - evaluated_limits - evaluated_at - request_id properties: target: $ref: "#/components/schemas/PlatformUsageTarget" description: | Normalized concrete ORGANIZATION, USER, or AGENT evaluated. USER targets contain the canonical user_id, not the supplied alias ID or email. Included even when no configured policies apply. usage_selector: $ref: "#/components/schemas/PlatformUsageSelector" description: Exact evaluated selector, including case and padding of client_id; never normalized. applicable_policy_count: type: integer minimum: 0 description: | Number of applicable configured policies, including UNLIMITED policies. Zero explicitly means no configured policy matched, not an unlimited configured rule. Included even when zero. decision: $ref: "#/components/schemas/PlatformUsageLimitDecision" description: Overall configured-budget status across all evaluated limits, not runtime admission. effective_limits: type: array minItems: 1 maxItems: 2 items: $ref: "#/components/schemas/PlatformUsageHeadroomValue" description: | Tightest remaining budget per finite unit, ordered USD then CREDITS. remaining is headroom after accrued usage and approved one-period grants, not a configured cap. Units are never combined or converted. When no finite policy applies, contains a single UNLIMITED entry without remaining, unit, or enforcement, including when applicable_policy_count is zero. This configured-budget result is not a runtime admission guarantee. evaluated_limits: type: array items: $ref: "#/components/schemas/PlatformEvaluatedLimit" description: Per-rule evaluation details. evaluated_at: type: string format: date-time description: ISO 8601 timestamp of when usage counters were read. request_id: type: string description: Request identifier for correlating this response. PlatformEvaluateCallerUsageLimitRequest: type: object additionalProperties: false description: | Non-admin evaluation request. Only omission of target selects the authenticated canonical user; null, empty, and incomplete targets are invalid. Explicit USER targets accept the caller's canonical ID, known alias IDs, email, or known alias emails; every supplied field must identify the caller. AGENT targets require current edit permission and evaluate aggregate agent usage, including organization limits. The authenticated identity is never replaced by the selected target. required: - usage_selector properties: target: $ref: "#/components/schemas/PlatformUsageTarget" description: Optional self or editable agent target. Omit to evaluate self. usage_selector: $ref: "#/components/schemas/PlatformUsageSelector" description: Usage to evaluate for the target; always required. allOf: - properties: usage_selector: description: Explicit spend-client context; never inferred from the caller. required: - client_id PlatformRequestStatus: type: string enum: - PENDING - APPROVED - DENIED description: Stored request state. PlatformRequestFilter: type: object additionalProperties: false required: - field - values description: A status filter using the backend's status-IN matching. properties: field: type: string pattern: ^status$ description: Allowed field is status, spelled exactly in lowercase. values: type: array minItems: 1 description: Status values to match with OR. items: $ref: "#/components/schemas/PlatformRequestStatus" description: One supported request status. operator: allOf: - $ref: "#/components/schemas/PlatformFilterOperator" description: Canonical Platform filter operator. enum: - EQUALS default: EQUALS description: Only EQUALS is supported; defaults to EQUALS when omitted. PlatformRequestResolutionFields: type: object description: | Valid input and response combinations: PERIOD may omit both fields; USER and ALL forbid an identifier; GROUP requires a nonempty canonical IdP group ID; DEPARTMENT requires a nonempty explicit department name. ONGOING requires a resolution target. allOf: - oneOf: - description: Omitted resolution fields for an unresolved request or PERIOD approval. properties: scope: description: Only PERIOD can omit the resolution target when scope is present. enum: - PERIOD not: anyOf: - required: - resolution_target description: Detect a resolution target. - required: - resolution_target_id description: Detect a resolution target identifier. - description: USER and ALL do not have a separate resolution target identifier. required: - resolution_target properties: resolution_target: description: User or organization approval breadth. enum: - USER - ALL not: required: - resolution_target_id - description: GROUP and DEPARTMENT require their corresponding identifier. required: - resolution_target - resolution_target_id properties: resolution_target: description: Group or department approval breadth. enum: - GROUP - DEPARTMENT resolution_target_id: description: Canonical IdP group ID or explicit department name. minLength: 1 PlatformRequestPeriod: type: string pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$ description: UTC calendar month in YYYY-MM format, assigned by the server at creation. PlatformRecordedApprovedAmount: type: string pattern: ^-?([1-9][0-9]*(\.[0-9]+)?|0\.[0-9]*[1-9][0-9]*)$ description: | Recorded additive amount in the applicable rule's denomination, encoded as a plain decimal string. Positive for approved increases; negative for an administrator's PERIOD decrease of the current period's approved increases. The backend stores float32 values, not arbitrary-precision decimals. PlatformRequestScope: type: string enum: - PERIOD - ONGOING description: | PERIOD records a decision for the stored request month; approval requires the current UTC month. Existing enforcement consumes eligible USER current-period grants without changing standing rules; no agent or other unsupported target capacity is added. ONGOING identifies a standing-rule approval in existing app records; this API does not support creating ONGOING approvals. PlatformRequestResolutionTarget: type: string enum: - USER - ALL - DEPARTMENT - GROUP description: Breadth of the approved increase; GROUP identifies an IdP group. PlatformLimitIncreaseRequest: type: object additionalProperties: false required: - request_id - entity_type - entity_id - client_id - requester_user_id - period - status - created_at description: Stored user or agent request, with optional resolution fields when available. properties: request_id: type: string description: Server-assigned resource identifier, distinct from the response's trace request_id. entity_type: type: string enum: - USER - AGENT description: Whether the request concerns a user or an agent. entity_id: type: string description: Canonical user ID or agent ID whose limit the request concerns. client_id: type: string description: Spend client for this user or agent request. requester_user_id: type: string description: Authenticated user who created the request. business_justification: type: string description: Stored explanation of why the increase is needed, when supplied. period: $ref: "#/components/schemas/PlatformRequestPeriod" description: Stored request month; resolution does not change this month. status: $ref: "#/components/schemas/PlatformRequestStatus" description: Current stored request state. resolved_by_user_id: type: string description: User who resolved the request, when available. approved_increase_amount: $ref: "#/components/schemas/PlatformRecordedApprovedAmount" description: Stored additive approval amount, when available. scope: $ref: "#/components/schemas/PlatformRequestScope" description: Approval scope derived from the stored ongoing flag, when available. resolution_target: $ref: "#/components/schemas/PlatformRequestResolutionTarget" description: Stored approval breadth, when available. resolution_target_id: type: string description: Stored department or canonical IdP group ID, when available. resolution_note: type: string description: Stored denial note, when supplied. created_at: type: string format: date-time description: Request creation time. updated_at: type: string format: date-time description: Last stored update time; this is the resolution time for resolved requests. allOf: - $ref: "#/components/schemas/PlatformRequestResolutionFields" description: Shared resolution target and identifier pairings. PlatformRequestListResponse: type: object additionalProperties: false description: Bounded page of authorized requests with opaque continuation state. required: - results - has_more - request_id properties: results: type: array description: Requests visible to the caller under the current filters and authorization. items: $ref: "#/components/schemas/PlatformLimitIncreaseRequest" description: One authorized request in the page. has_more: type: boolean description: Whether a further page is available through next_cursor. next_cursor: type: - string - "null" description: Opaque nonempty continuation when has_more is true; null or omitted otherwise. request_id: type: string description: Trace identifier for this list response, not a request resource ID. allOf: - description: Continuation availability must agree with the cursor. oneOf: - description: A further page requires a usable continuation cursor. required: - next_cursor properties: has_more: type: boolean description: Further-page discriminator. enum: - true next_cursor: type: string description: Opaque nonempty cursor for the next authorized page. minLength: 1 - description: The last page has no continuation cursor. properties: has_more: type: boolean description: Last-page discriminator. enum: - false next_cursor: type: "null" description: If present on the last page, the cursor must be null. PlatformPersonalRequestCreate: type: object additionalProperties: false required: - client_id description: New request for the authenticated canonical user in the server's current UTC month. properties: client_id: type: string minLength: 1 maxLength: 256 pattern: ^[^\x00-\x1f\x7f]+$ not: enum: - __deleted_clients__ description: | Explicit opaque spend-client ID, retained without normalization and not inferred from the authenticating OAuth application. Control characters and the synthetic __deleted_clients__ aggregation ID are not valid spend-client IDs. business_justification: type: string maxLength: 4096 description: Optional explanation of why the increase is needed. PlatformRequestResponse: type: object additionalProperties: false description: Single authorized request with the enclosing response's trace identifier. required: - request - request_id properties: request: $ref: "#/components/schemas/PlatformLimitIncreaseRequest" description: Authorized request at its current stored state. request_id: type: string description: Trace identifier, distinct from the resource ID. PlatformAgentRequestCreate: type: object additionalProperties: false required: - agent_id - client_id description: New client-scoped request for an editable agent in the server's current UTC month. properties: agent_id: type: string minLength: 1 maxLength: 256 description: Identifier of the agent whose limit the request concerns. client_id: type: string minLength: 1 maxLength: 256 pattern: ^[^\x00-\x1f\x7f]+$ not: enum: - __deleted_clients__ description: | Explicit opaque spend-client ID, retained without normalization and not inferred from the authenticating OAuth application. Control characters and the synthetic __deleted_clients__ aggregation ID are not valid spend-client IDs. business_justification: type: string maxLength: 4096 description: Optional explanation of why the increase is needed. PlatformApprovedIncreaseAmount: type: string pattern: ^([1-9][0-9]*(\.[0-9]+)?|0\.[0-9]*[1-9][0-9]*)$ description: | Recorded positive additive increase in the applicable rule's denomination, encoded as a plain decimal string. Existing enforcement consumes eligible USER current-period grants without changing standing rules. This does not add capacity for agents or other unsupported targets. The backend stores float32 values, not arbitrary-precision decimals. PlatformAdministrativeRequestUpdate: type: object additionalProperties: false required: - status description: | Resolve a pending request. PERIOD approval records a positive additive amount for the stored current UTC month; expired approvals return 409. The existing backend consumes eligible USER current-period grants without changing standing rules; no agent or other unsupported target capacity is added. ONGOING approval is unavailable on this API and returns 503. GROUP and DEPARTMENT resolution targets are not accepted for new approvals. Request identity and period cannot change. properties: status: type: string enum: - APPROVED - DENIED description: Requested terminal state. approved_increase_amount: $ref: "#/components/schemas/PlatformApprovedIncreaseAmount" description: Positive increase amount to record, required only for approval. scope: $ref: "#/components/schemas/PlatformRequestScope" default: PERIOD description: Approval scope; omission selects PERIOD. ONGOING returns 503 on this API. resolution_target: description: Approval breadth; USER or ALL only. Required for an ONGOING approval. x-go-type: RequestResolutionTarget allOf: - $ref: "#/components/schemas/PlatformRequestResolutionTarget" description: Shared stored resolution target vocabulary. - type: string enum: - USER - ALL description: Targets accepted for new approvals. resolution_target_id: type: string maxLength: 256 description: | Not accepted for new approvals. Stored GROUP and DEPARTMENT records retain their identifiers in request responses. resolution_note: type: string maxLength: 4096 description: Optional note recorded when denying the request. allOf: - $ref: "#/components/schemas/PlatformRequestResolutionFields" description: Shared resolution target and identifier pairings. - description: Approval records an increase amount; denial can record a note. oneOf: - description: Record approval with a positive increase amount. required: - approved_increase_amount properties: status: description: Approval discriminator. enum: - APPROVED not: description: Approval does not record a resolution note. required: - resolution_note oneOf: - description: A PERIOD approval records a current-month grant; existing enforcement consumes eligible USER grants. properties: scope: description: Period approval, also selected when scope is omitted. enum: - PERIOD - description: ONGOING input is recognized but returns 503 without changing the request. required: - scope - resolution_target properties: scope: description: Ongoing approval discriminator. enum: - ONGOING - description: Deny without approval fields. properties: status: description: Denial discriminator. enum: - DENIED not: description: Approval fields are not denial inputs. anyOf: - required: - approved_increase_amount description: Detect an approval amount. - required: - scope description: Detect an approval scope. - required: - resolution_target description: Detect an approval target. - required: - resolution_target_id description: Detect an approval target identifier. PlatformOAuthClientFilter: type: object additionalProperties: false required: - field - values description: A filter on one OAuth client field. properties: field: type: string pattern: ^is_active$ description: The client field to filter on. The only supported field is is_active. values: type: array minItems: 1 description: The values to match. A client matches when any value matches. items: type: string pattern: ^(true|false)$ description: "\"true\" matches active clients. \"false\" matches inactive clients." operator: allOf: - $ref: "#/components/schemas/PlatformFilterOperator" description: Canonical Platform filter operator. enum: - EQUALS default: EQUALS description: The only supported operator is EQUALS. Defaults to EQUALS. PlatformOAuthClientRegistrationType: type: string description: How an OAuth client was registered. enum: - STATIC x-enumDescriptions: STATIC: An admin created the client. x-speakeasy-enum-descriptions: STATIC: An admin created the client. PlatformOAuthClientType: type: string description: Whether an OAuth client can keep a secret. enum: - CONFIDENTIAL - PUBLIC x-enumDescriptions: CONFIDENTIAL: The client can keep a secret, for example a server-side application. PUBLIC: The client cannot keep a secret, for example a desktop or command-line application. x-speakeasy-enum-descriptions: CONFIDENTIAL: The client can keep a secret, for example a server-side application. PUBLIC: The client cannot keep a secret, for example a desktop or command-line application. PlatformOAuthGrantType: type: string description: An OAuth grant type. enum: - AUTHORIZATION_CODE - CLIENT_CREDENTIALS - REFRESH_TOKEN - DEVICE_CODE - TOKEN_EXCHANGE - JWT_BEARER x-enumDescriptions: AUTHORIZATION_CODE: The authorization code grant. CLIENT_CREDENTIALS: The client credentials grant. REFRESH_TOKEN: The refresh token grant. DEVICE_CODE: The device authorization grant. TOKEN_EXCHANGE: The token exchange grant. JWT_BEARER: The JWT bearer assertion grant. x-speakeasy-enum-descriptions: AUTHORIZATION_CODE: The authorization code grant. CLIENT_CREDENTIALS: The client credentials grant. REFRESH_TOKEN: The refresh token grant. DEVICE_CODE: The device authorization grant. TOKEN_EXCHANGE: The token exchange grant. JWT_BEARER: The JWT bearer assertion grant. PlatformOAuthTokenEndpointAuthMethod: type: string description: How an OAuth client authenticates to the token endpoint. enum: - CLIENT_SECRET_BASIC - CLIENT_SECRET_POST - NO_AUTHENTICATION - PRIVATE_KEY_JWT - TLS_CLIENT_AUTH x-enumDescriptions: CLIENT_SECRET_BASIC: The client sends its secret in an HTTP Basic Authorization header. CLIENT_SECRET_POST: The client sends its secret in the request body. NO_AUTHENTICATION: The client does not authenticate. Public clients use this method. PRIVATE_KEY_JWT: The client signs a JWT with its private key. TLS_CLIENT_AUTH: The client authenticates with a mutual TLS certificate. x-speakeasy-enum-descriptions: CLIENT_SECRET_BASIC: The client sends its secret in an HTTP Basic Authorization header. CLIENT_SECRET_POST: The client sends its secret in the request body. NO_AUTHENTICATION: The client does not authenticate. Public clients use this method. PRIVATE_KEY_JWT: The client signs a JWT with its private key. TLS_CLIENT_AUTH: The client authenticates with a mutual TLS certificate. PlatformOAuthClientAiGateway: type: object description: LLM Gateway details of an OAuth client. additionalProperties: false required: - usage_client_id properties: usage_client_id: type: string description: | The spend-client ID that usage records and usage limits use for this client. Send it as the client_id of a usage limit. It is an opaque, case-sensitive string; do not build it from client_id. PlatformOAuthClient: type: object description: An OAuth client that an admin created for the workspace. additionalProperties: false required: - client_id - display_name - registration_type - grant_types - redirect_uris - is_active properties: client_id: type: string description: | The OAuth client_id that the client sends to the authorization server. This is not the ID that usage records and usage limits use; see ai_gateway.usage_client_id. display_name: type: string description: The client name that admins gave the client, or client_id when it has no name. registration_type: $ref: "#/components/schemas/PlatformOAuthClientRegistrationType" description: How the client was registered. client_type: $ref: "#/components/schemas/PlatformOAuthClientType" description: Whether the client can keep a secret. Absent when it is not set. grant_types: type: array description: The OAuth grant types that the client can use. items: $ref: "#/components/schemas/PlatformOAuthGrantType" description: An OAuth grant type. token_endpoint_auth_method: $ref: "#/components/schemas/PlatformOAuthTokenEndpointAuthMethod" description: | How the client authenticates to the token endpoint. Absent when it is not set. redirect_uris: type: array description: The redirect URIs that the client can use. items: type: string description: A redirect URI. is_active: type: boolean description: | Whether the client is active. A client that an admin disabled is inactive and cannot authenticate. created_at: type: string format: date-time description: When the client was created. Absent when it is not known. ai_gateway: $ref: "#/components/schemas/PlatformOAuthClientAiGateway" description: | LLM Gateway details. Present only when the client can call the Glean LLM Gateway. PlatformListOAuthClientsResponse: type: object description: One page of OAuth clients. additionalProperties: false required: - results - has_more - request_id properties: results: type: array description: The clients on this page, ordered by display_name and then by client_id. items: $ref: "#/components/schemas/PlatformOAuthClient" has_more: type: boolean description: Whether more clients are available after this page. next_cursor: type: - string - "null" description: Opaque cursor for the next page; null or absent when has_more is false. request_id: type: string description: Request identifier for correlating this response. PlatformDepartmentFilter: type: object additionalProperties: false required: - field - values description: A filter on one department field. properties: field: type: string pattern: ^is_active$ description: The department field to filter on. The only supported field is is_active. values: type: array minItems: 1 description: The values to match. A department matches when any value matches. items: type: string pattern: ^(true|false)$ description: "\"true\" matches active departments. \"false\" matches inactive departments." operator: allOf: - $ref: "#/components/schemas/PlatformFilterOperator" description: Canonical Platform filter operator. enum: - EQUALS default: EQUALS description: The only supported operator is EQUALS. Defaults to EQUALS. PlatformDepartmentReference: type: object description: A reference to a department in the Glean directory. required: - department_id - display_name properties: department_id: type: string description: | Opaque department ID. The users and departments APIs return the same ID for the same department. A renamed department gets a new ID. display_name: type: string description: Department name, exactly as the directory stores it. PlatformDepartment: description: A department in the Glean directory. allOf: - $ref: "#/components/schemas/PlatformDepartmentReference" - type: object required: - is_active properties: is_active: type: boolean description: | Whether at least one active user belongs to the department. A department that belongs only to inactive users, or that only a usage limit names, is inactive. PlatformListDepartmentsResponse: type: object description: One page of departments. additionalProperties: false required: - results - has_more - request_id properties: results: type: array description: | The departments on this page, ordered by display_name and then by department_id. items: $ref: "#/components/schemas/PlatformDepartment" has_more: type: boolean description: Whether more departments are available after this page. next_cursor: type: - string - "null" description: Opaque cursor for the next page; null or absent when has_more is false. request_id: type: string description: Request identifier for correlating this response. PlatformIdpGroupFilter: type: object additionalProperties: false required: - field - values description: A filter on one IdP group field. properties: field: type: string pattern: ^(is_active|provider_instance)$ description: | The IdP group field to filter on. The supported fields are is_active and provider_instance. values: type: array minItems: 1 description: The values to match. An IdP group matches when any value matches. items: type: string minLength: 1 description: | For is_active, "true" matches active IdP groups and "false" matches inactive IdP groups. For provider_instance, a datasource instance name. operator: allOf: - $ref: "#/components/schemas/PlatformFilterOperator" description: Canonical Platform filter operator. enum: - EQUALS default: EQUALS description: The only supported operator is EQUALS. Defaults to EQUALS. PlatformIdpGroupReference: type: object description: A reference to an identity provider (IdP) group in the Glean directory. required: - idp_group_id - display_name properties: idp_group_id: type: string description: | Opaque IdP group ID. The same group always gets the same ID. Callers must not parse or build it. display_name: type: string description: | Group name from the identity provider. When the provider has no display name, this is the group's name or ID in the provider. PlatformIdpGroup: description: An IdP group in the Glean directory. allOf: - $ref: "#/components/schemas/PlatformIdpGroupReference" - type: object required: - provider - provider_instance - is_active properties: provider: type: string description: | The identity provider datasource that the group comes from, for example "okta", "gdrive", or "o365". provider_instance: type: string description: | The datasource instance that the group comes from, for example "okta". A provider can have more than one instance. is_active: type: boolean description: | Whether Glean loaded the group from the directory. A group that only a usage limit names is inactive. PlatformListIdpGroupsResponse: type: object description: One page of IdP groups. additionalProperties: false required: - results - has_more - request_id properties: results: type: array description: | The IdP groups on this page, ordered by display_name and then by idp_group_id. items: $ref: "#/components/schemas/PlatformIdpGroup" has_more: type: boolean description: Whether more IdP groups are available after this page. next_cursor: type: - string - "null" description: Opaque cursor for the next page; null or absent when has_more is false. request_id: type: string description: Request identifier for correlating this response. PlatformUserFilter: type: object additionalProperties: false required: - field - values description: A filter on one user field. properties: field: type: string pattern: ^is_active$ description: The user field to filter on. The only supported field is is_active. values: type: array minItems: 1 description: The values to match. A user matches when any value matches. items: type: string pattern: ^(true|false)$ description: "\"true\" matches active users. \"false\" matches inactive users." operator: allOf: - $ref: "#/components/schemas/PlatformFilterOperator" description: Canonical Platform filter operator. enum: - EQUALS default: EQUALS description: The only supported operator is EQUALS. Defaults to EQUALS. PlatformUserInclude: type: string description: An optional field group to add to each user. enum: - DATASOURCE_PROFILES x-enumDescriptions: DATASOURCE_PROFILES: Add datasource_profiles, the user's accounts in connected apps. x-speakeasy-enum-descriptions: DATASOURCE_PROFILES: Add datasource_profiles, the user's accounts in connected apps. PlatformPersonType: type: string description: Person employment status or account type. enum: - FULL_TIME - CONTRACTOR - NON_EMPLOYEE - FORMER_EMPLOYEE PlatformUserManager: type: object description: The user that another user reports to. additionalProperties: false required: - user_id - display_name properties: user_id: type: string description: Opaque canonical Glean user ID of the manager. display_name: type: string description: The name that Glean shows for the manager. PlatformUserDatasourceProfile: type: object description: A user's account in a connected app. additionalProperties: false required: - datasource - handle properties: datasource: type: string description: Datasource of the account, for example slack or github. handle: type: string description: The account's handle or display name in the app. account_id: type: string description: | The app's own ID for the account. Present only when Glean knows it, for example the Slack user ID. profile_url: type: string description: Web URL of the account's profile. PlatformUser: type: object description: A user in the Glean directory. additionalProperties: false required: - user_id - display_name - is_active properties: user_id: type: string description: | Opaque canonical Glean user ID. Other Platform APIs, such as usage limits, accept and return this ID. display_name: type: string description: The name that Glean shows for the user. email: type: string description: Primary email address. alias_emails: type: array description: | The user's other email addresses, sorted, without the primary email. Absent when the user has none or the workspace does not show alias emails. items: type: string description: An alias email address. is_active: type: boolean description: | Whether the user is active. A user whose type is FORMER_EMPLOYEE is inactive. user_type: $ref: "#/components/schemas/PlatformPersonType" description: | Employment status or account type. Absent when the workspace hides the employee type attribute. title: type: string description: Job title. department: $ref: "#/components/schemas/PlatformDepartmentReference" description: The user's department. Absent when the user has no department. manager: $ref: "#/components/schemas/PlatformUserManager" description: | The user's direct manager. Absent when the user has no manager or the manager is not in the directory. An inactive manager is still returned. photo_url: type: string description: Avatar URL. datasource_profiles: type: array description: | The user's accounts in connected apps. Present only when include contains DATASOURCE_PROFILES. Each account appears once, even when more than one connected app instance reports it. items: $ref: "#/components/schemas/PlatformUserDatasourceProfile" PlatformListUsersResponse: type: object description: One page of users. additionalProperties: false required: - results - has_more - request_id properties: results: type: array description: The users on this page, ordered by display_name and then by user_id. items: $ref: "#/components/schemas/PlatformUser" has_more: type: boolean description: Whether more users are available after this page. next_cursor: type: - string - "null" description: Opaque cursor for the next page; null or absent when has_more is false. request_id: type: string description: Request identifier for correlating this response. PlatformAdminAgentFilter: type: object additionalProperties: false required: - field - values description: A filter on one agent field. properties: field: type: string pattern: ^is_active$ description: The agent field to filter on. The only supported field is is_active. values: type: array minItems: 1 description: The values to match. An agent matches when any value matches. items: type: string pattern: ^(true|false)$ description: "\"true\" matches active agents. \"false\" matches deleted agents." operator: allOf: - $ref: "#/components/schemas/PlatformFilterOperator" description: Canonical Platform filter operator. enum: - EQUALS default: EQUALS description: The only supported operator is EQUALS. Defaults to EQUALS. PlatformAdminAgent: type: object description: An agent in the workspace. additionalProperties: false required: - agent_id - display_name - is_active properties: agent_id: type: string description: | Opaque agent ID. Other Platform APIs, such as usage limits, accept and return this ID. display_name: type: string description: The name that Glean shows for the agent. is_active: type: boolean description: Whether the agent is active. A deleted agent is inactive. PlatformListAdminAgentsResponse: type: object description: One page of agents. additionalProperties: false required: - results - has_more - request_id properties: results: type: array description: The agents on this page, ordered by display_name and then by agent_id. items: $ref: "#/components/schemas/PlatformAdminAgent" has_more: type: boolean description: Whether more agents are available after this page. next_cursor: type: - string - "null" description: Opaque cursor for the next page; null or absent when has_more is false. request_id: type: string description: Request identifier for correlating this response. PlatformTriggerStatus: type: string description: Current trigger lifecycle state. example: ENABLED enum: - ENABLED - DISABLED PlatformTriggerAuth: type: object additionalProperties: false required: - type - secret description: Optional caller credential sent as an HTTP auth header on each delivery, in addition to the HMAC signature. Lets the receiving endpoint authenticate the request. On update, omit `auth` to preserve the existing credential; there is no in-place removal — recreate the trigger to remove auth. properties: type: type: string description: Credential scheme. enum: - BEARER secret: type: string writeOnly: true description: Secret credential value. Write-only; never returned on reads. example: secret_test_123 PlatformTriggerDelivery: type: object additionalProperties: false required: - webhook_url properties: webhook_url: type: string format: uri pattern: ^https:// description: HTTPS URL that signed events are delivered to. example: https://customer.app/webhook auth: $ref: "#/components/schemas/PlatformTriggerAuth" PlatformTrigger: type: object required: - trigger_id - preset_id - status - delivery - created_at - updated_at properties: trigger_id: type: string description: ID of the trigger. example: trigger_test_123 preset_id: type: string description: ID of the preset this trigger was created from. example: GITHUB_1 description: type: string description: Optional caller-supplied note describing this trigger. example: Reviews I am tagged on, sent to my team's review channel status: $ref: "#/components/schemas/PlatformTriggerStatus" inputs: type: object additionalProperties: true description: Values supplied for the preset's inputs. example: repository: acme/payments-api delivery: $ref: "#/components/schemas/PlatformTriggerDelivery" created_at: type: string format: date-time description: Time the trigger was created. updated_at: type: string format: date-time description: Time the trigger was last updated. PlatformTriggerListResponse: type: object required: - results - has_more - next_cursor - request_id properties: results: type: array description: Triggers owned by the caller. items: $ref: "#/components/schemas/PlatformTrigger" has_more: type: boolean description: Whether additional results are available. next_cursor: type: - string - "null" description: Cursor for the next page, or null when no more results are available. request_id: type: string description: Platform-generated request ID for support correlation. PlatformTriggerCreateRequest: type: object additionalProperties: false required: - preset_id - delivery example: preset_id: GITHUB_1 inputs: repository: "{repository}" delivery: webhook_url: https://example.com/webhook properties: preset_id: type: string description: ID of the preset to instantiate. example: GITHUB_1 description: type: string description: Optional note describing this trigger. example: Reviews I am tagged on, sent to my team's review channel inputs: type: object additionalProperties: true description: Values for the preset's inputs. example: repository: acme/payments-api delivery: $ref: "#/components/schemas/PlatformTriggerDelivery" PlatformTriggerWithSecret: allOf: - $ref: "#/components/schemas/PlatformTrigger" - type: object required: - signing_secret properties: signing_secret: type: string pattern: ^whsec_[A-Za-z0-9+/=]+$ example: whsec_xxx description: Secret for verifying webhook signatures, serialized as `whsec_` following Standard Webhooks. Returned only when the trigger is created and cannot be retrieved later. Store it securely. PlatformTriggerCreateResponse: type: object required: - trigger - request_id properties: trigger: $ref: "#/components/schemas/PlatformTriggerWithSecret" request_id: type: string description: Platform-generated request ID for support correlation. PlatformTriggerWebhookEventBase: type: object required: - version - trigger_id - event_type - datasource - reason - doc_type - doc_id - view_url - title properties: version: type: string description: Webhook payload schema version. pattern: ^1$ trigger_id: type: string description: ID of the Platform trigger that produced the event. example: trigger_test_123 event_type: type: string description: Kind of trigger event. datasource: type: string description: Datasource the event originated from. example: GITHUB reason: type: string description: Why the event fired. example: REVIEW_REQUESTED doc_type: type: string description: Datasource-specific object type. example: pull doc_id: type: string description: Identifier of the document the event is about. example: GITHUB_pull_123 view_url: type: string description: Link to the document in its source system. example: https://github.com/acme/payments-api/pull/123 title: type: string description: Title of the document, or the subject for email. example: "Bug: login fails on Safari" event_time: type: string format: date-time description: Relevant event time. Document changes use the source-observed time when available and otherwise the document ingestion time; content schedules use the scheduled time. Omitted when no timestamp is available. PlatformDocumentChangeWebhookEvent: allOf: - $ref: "#/components/schemas/PlatformTriggerWebhookEventBase" - type: object required: - event_type properties: event_type: type: string pattern: ^DOCUMENT_CHANGE$ content: type: string description: Email body content when the event is for an email document. content_truncated: type: boolean description: Present and true when source content exceeded the delivery size limit. example: version: "1" trigger_id: trigger_test_123 event_type: DOCUMENT_CHANGE datasource: GITHUB reason: REVIEW_REQUESTED doc_type: pull doc_id: GITHUB_pull_123 view_url: https://github.com/acme/payments-api/pull/123 title: Add retry backoff to the crawler event_time: "2025-04-23T11:00:00Z" PlatformContentScheduleWebhookEvent: allOf: - $ref: "#/components/schemas/PlatformTriggerWebhookEventBase" - type: object required: - event_type - time_offset_seconds properties: event_type: type: string pattern: ^CONTENT_SCHEDULE$ time_offset_seconds: type: integer format: int32 description: Offset in seconds from the scheduled time at which the trigger fired. example: version: "1" trigger_id: trigger_test_123 event_type: CONTENT_SCHEDULE datasource: GOOGLECALENDAR reason: CONTENT_SCHEDULE doc_type: event doc_id: GCAL_event_123 view_url: https://calendar.google.com/event?eid=abc title: Weekly Sync event_time: "2025-04-23T12:00:00Z" time_offset_seconds: 1800 PlatformTriggerWebhookEvent: description: Every delivered webhook is one of these two variants. A trigger with a cron schedule carries no document and so cannot be delivered over a webhook. oneOf: - $ref: "#/components/schemas/PlatformDocumentChangeWebhookEvent" - $ref: "#/components/schemas/PlatformContentScheduleWebhookEvent" discriminator: propertyName: event_type mapping: DOCUMENT_CHANGE: "#/components/schemas/PlatformDocumentChangeWebhookEvent" CONTENT_SCHEDULE: "#/components/schemas/PlatformContentScheduleWebhookEvent" PlatformTriggerGetResponse: type: object required: - trigger - request_id properties: trigger: $ref: "#/components/schemas/PlatformTrigger" request_id: type: string description: Platform-generated request ID for support correlation. PlatformTriggerUpdateRequest: type: object additionalProperties: false description: Partial update. Only the supplied fields are changed. example: inputs: repository: "{repository}" delivery: webhook_url: https://example.com/webhook properties: status: $ref: "#/components/schemas/PlatformTriggerStatus" description: type: string description: Optional note describing this trigger. example: Reviews I am tagged on, sent to my team's review channel inputs: type: object additionalProperties: true description: Values for the preset's inputs. example: repository: acme/payments-api delivery: $ref: "#/components/schemas/PlatformTriggerDelivery" PlatformTriggerEventSearchRequest: type: object additionalProperties: false example: page_size: 10 properties: page_size: type: integer description: Maximum number of events to return. minimum: 1 maximum: 100 default: 10 PlatformTriggerEventType: type: string description: The kind of event. example: DOCUMENT_CHANGE enum: - DOCUMENT_CHANGE x-enumDescriptions: DOCUMENT_CHANGE: A document was created, updated, or deleted. x-speakeasy-enum-descriptions: DOCUMENT_CHANGE: A document was created, updated, or deleted. PlatformTriggerEventReason: type: string description: Why the event fired. example: REVIEW_REQUESTED enum: - CREATED - UPDATED - DELETED - MEETS_CONDITION - ASSIGNED - UNASSIGNED - LABELED - UNLABELED - REVIEW_REQUESTED - REVIEW_REQUEST_REMOVED - READY_FOR_REVIEW - CONVERTED_TO_DRAFT - WEBHOOK_UPDATED - WEBHOOK_CREATED x-enumDescriptions: CREATED: The document was created. UPDATED: The document was updated. DELETED: The document was deleted. MEETS_CONDITION: The document started matching the trigger's conditions. ASSIGNED: The item was assigned to someone. UNASSIGNED: The item was unassigned. LABELED: A label was added. UNLABELED: A label was removed. REVIEW_REQUESTED: A review was requested. REVIEW_REQUEST_REMOVED: A review request was withdrawn. READY_FOR_REVIEW: A draft was marked ready for review. CONVERTED_TO_DRAFT: The item was converted back to a draft. WEBHOOK_UPDATED: The source system sent a webhook update. WEBHOOK_CREATED: The source system sent a webhook creation event. x-speakeasy-enum-descriptions: CREATED: The document was created. UPDATED: The document was updated. DELETED: The document was deleted. MEETS_CONDITION: The document started matching the trigger's conditions. ASSIGNED: The item was assigned to someone. UNASSIGNED: The item was unassigned. LABELED: A label was added. UNLABELED: A label was removed. REVIEW_REQUESTED: A review was requested. REVIEW_REQUEST_REMOVED: A review request was withdrawn. READY_FOR_REVIEW: A draft was marked ready for review. CONVERTED_TO_DRAFT: The item was converted back to a draft. WEBHOOK_UPDATED: The source system sent a webhook update. WEBHOOK_CREATED: The source system sent a webhook creation event. PlatformTriggerEvent: type: object required: - event_type - doc_id - datasource - doc_type - view_url - title - reason - event_time description: A content event a trigger can fire on. properties: event_type: $ref: "#/components/schemas/PlatformTriggerEventType" datasource: type: string description: Datasource the event originated from. example: GITHUB reason: $ref: "#/components/schemas/PlatformTriggerEventReason" doc_type: type: string description: Datasource-specific object type. example: pull doc_id: type: string description: Identifier of the document the event is about. view_url: type: string description: Link to the document in its source system. title: type: string description: Title of the document, or the subject for email. event_time: type: string format: date-time description: "When the event happened at the source: the document's own change timestamp for a document change, and the scheduled time for a content schedule. Omitted when the source did not supply one." PlatformTriggerEventSearchResponse: type: object required: - results - has_more - request_id properties: results: type: array description: Matching events, most recent first. items: $ref: "#/components/schemas/PlatformTriggerEvent" has_more: type: boolean description: | Whether more events matched than were returned. Raise `page_size` to see more; cursor-based paging is not offered yet. request_id: type: string description: Unique identifier for this request, for support and debugging. PlatformTriggerPresetSummary: type: object required: - preset_id - datasource - display_name properties: preset_id: type: string description: ID of the preset. Pass this when creating a trigger. example: GITHUB_1 datasource: type: string description: Datasource the preset fires on. example: github display_name: type: string description: Human-readable preset name. example: Review requested from me description: type: string description: Human-readable description of when the preset fires. example: A review is requested from the trigger creator on a pull request PlatformTriggerPresetListResponse: type: object required: - results - has_more - next_cursor - request_id properties: results: type: array description: Trigger presets available to the caller. items: $ref: "#/components/schemas/PlatformTriggerPresetSummary" has_more: type: boolean description: Whether additional results are available. next_cursor: type: - string - "null" description: Cursor for the next page, or null when no more results are available. request_id: type: string description: Platform-generated request ID for support correlation. PlatformTriggerPresetInputType: type: string description: Type of a preset input. example: PICKLIST enum: - PICKLIST - TEXT - USER PlatformTriggerPresetInputValue: type: object required: - value - display_name properties: value: type: string description: | The exact value to send in the trigger's `inputs` for this choice (e.g. a channel name, a user's email, etc). example: acme/payments-api display_name: type: string description: Human-readable name for this value. example: acme/payments-api PlatformTriggerPresetInput: type: object required: - field - type - display_name - is_required properties: field: type: string description: Identifier of the input, supplied as a key in the trigger's `inputs`. example: repository type: $ref: "#/components/schemas/PlatformTriggerPresetInputType" display_name: type: string description: Human-readable name for the input. example: Repository is_required: type: boolean description: Whether the caller must supply a value for this input. values: type: array description: | Bounded initial set of selectable values for a picklist input. Omitted entirely for free-text inputs. items: $ref: "#/components/schemas/PlatformTriggerPresetInputValue" is_truncated: type: boolean description: | Whether additional selectable values were omitted from `values`. When true, use GET /trigger-presets/{preset_id}/input-values with a query to narrow the result set. PlatformTriggerPreset: allOf: - $ref: "#/components/schemas/PlatformTriggerPresetSummary" - type: object required: - inputs properties: inputs: type: array description: Inputs the caller may supply when creating a trigger from this preset. items: $ref: "#/components/schemas/PlatformTriggerPresetInput" PlatformTriggerPresetGetResponse: type: object required: - trigger_preset - request_id properties: trigger_preset: $ref: "#/components/schemas/PlatformTriggerPreset" request_id: type: string description: Platform-generated request ID for support correlation. PlatformTriggerPresetInputValueListResponse: type: object required: - results - is_truncated - request_id properties: results: type: array description: The bounded set of selectable values matching the query. items: $ref: "#/components/schemas/PlatformTriggerPresetInputValue" is_truncated: type: boolean description: | Whether additional matches were omitted. When true, refine `query` to narrow the result set. request_id: type: string description: Platform-generated request ID for support correlation. PlatformTriggerPresetEventSearchRequest: type: object additionalProperties: false example: inputs: repository: "{repository}" page_size: 10 properties: inputs: type: object description: | Values for the preset's input fields, keyed by field name. additionalProperties: type: string example: repository: acme/payments-api page_size: type: integer description: Maximum number of events to return. minimum: 1 maximum: 100 default: 10 PlatformChatStreamResponseCreatedServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: RESPONSE_CREATED data: $ref: "#/components/schemas/PlatformChatStreamResponseCreated" PlatformChatStreamProgressServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: RESPONSE_PROGRESS data: $ref: "#/components/schemas/PlatformChatStreamProgress" PlatformChatStreamOutputTextDeltaServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: RESPONSE_OUTPUT_TEXT_DELTA data: $ref: "#/components/schemas/PlatformChatStreamOutputTextDelta" PlatformChatStreamOutputTextDoneServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: RESPONSE_OUTPUT_TEXT_DONE data: $ref: "#/components/schemas/PlatformChatStreamOutputTextDone" PlatformChatStreamResponseCompletedServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: RESPONSE_COMPLETED data: $ref: "#/components/schemas/PlatformChatStreamResponseCompleted" PlatformChatStreamResponseFailedServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: RESPONSE_FAILED data: $ref: "#/components/schemas/PlatformChatStreamResponseFailed" PlatformChatStreamEventServerSentEvent: description: A typed server-sent event. oneOf: - $ref: "#/components/schemas/PlatformChatStreamResponseCreatedServerSentEvent" - $ref: "#/components/schemas/PlatformChatStreamProgressServerSentEvent" - $ref: "#/components/schemas/PlatformChatStreamOutputTextDeltaServerSentEvent" - $ref: "#/components/schemas/PlatformChatStreamOutputTextDoneServerSentEvent" - $ref: "#/components/schemas/PlatformChatStreamResponseCompletedServerSentEvent" - $ref: "#/components/schemas/PlatformChatStreamResponseFailedServerSentEvent" discriminator: propertyName: event mapping: RESPONSE_CREATED: "#/components/schemas/PlatformChatStreamResponseCreatedServerSentEvent" RESPONSE_PROGRESS: "#/components/schemas/PlatformChatStreamProgressServerSentEvent" RESPONSE_OUTPUT_TEXT_DELTA: "#/components/schemas/PlatformChatStreamOutputTextDeltaServerSentEvent" RESPONSE_OUTPUT_TEXT_DONE: "#/components/schemas/PlatformChatStreamOutputTextDoneServerSentEvent" RESPONSE_COMPLETED: "#/components/schemas/PlatformChatStreamResponseCompletedServerSentEvent" RESPONSE_FAILED: "#/components/schemas/PlatformChatStreamResponseFailedServerSentEvent" PlatformSkillSourcePreviewStreamScanServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: SCAN data: $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamScan" PlatformSkillSourcePreviewStreamProgressServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: PROGRESS data: $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamProgress" PlatformSkillSourcePreviewStreamSkillServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: SKILL data: $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamSkill" PlatformSkillSourcePreviewStreamResultServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: RESULT data: $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamResult" PlatformSkillSourcePreviewStreamErrorServerSentEvent: type: object required: - event - data properties: id: type: string event: type: string const: ERROR data: $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamError" PlatformSkillSourcePreviewStreamEventServerSentEvent: description: A typed server-sent event. oneOf: - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamScanServerSentEvent" - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamProgressServerSentEvent" - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamSkillServerSentEvent" - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamResultServerSentEvent" - $ref: "#/components/schemas/PlatformSkillSourcePreviewStreamErrorServerSentEvent" discriminator: propertyName: event mapping: SCAN: "#/components/schemas/PlatformSkillSourcePreviewStreamScanServerSentEvent" PROGRESS: "#/components/schemas/PlatformSkillSourcePreviewStreamProgressServerSentEvent" SKILL: "#/components/schemas/PlatformSkillSourcePreviewStreamSkillServerSentEvent" RESULT: "#/components/schemas/PlatformSkillSourcePreviewStreamResultServerSentEvent" ERROR: "#/components/schemas/PlatformSkillSourcePreviewStreamErrorServerSentEvent" responses: PlatformBadRequest: description: Invalid request (malformed JSON, invalid parameter values, unknown fields). content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformUnauthorized: description: Missing or invalid authentication token. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformForbidden: description: Token valid but lacks permission for the requested operation. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformNotFound: description: Resource not found. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformRequestTimeout: description: Backend did not respond within the timeout window. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformRequestTooLarge: description: Request body exceeds the maximum allowed size. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformTooManyRequests: description: Rate limit exceeded. Includes Retry-After header. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformInternalServerError: description: Unexpected server-side failure. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformServiceUnavailable: description: Backend temporarily unavailable. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformConflict: description: Request conflicts with current state of the resource. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformUnprocessableEntity: description: Syntactically valid but semantically incorrect request. content: application/problem+json: schema: $ref: "#/components/schemas/PlatformProblemDetail" PlatformRequestResource: description: The authorized request in its current stored state. content: application/json: schema: $ref: "#/components/schemas/PlatformRequestResponse" description: Current authorized request with a response trace identifier. parameters: PageSize: name: page_size in: query description: Maximum page size; defaults to 20 and cannot exceed 100. A page may contain fewer results. schema: type: integer description: Requested upper bound on results in a page. minimum: 1 maximum: 100 default: 20 Cursor: name: cursor in: query description: Opaque cursor bound to filter fields, values, operators, and current authorization context. schema: type: string description: Opaque continuation returned by a previous list response. maxLength: 8192 Filters: name: filters in: query description: | JSON-encoded filters. Only the field status and operator EQUALS are supported. Multiple values OR within a filter. Multiple filters AND together. Cursors bind all filter fields, values, and operators. content: application/json: schema: type: array minItems: 1 maxItems: 100 description: Structured status filters, combined with AND. items: $ref: "#/components/schemas/PlatformRequestFilter" description: One status filter criterion. RequestId: name: request_id in: path required: true description: Opaque request identifier; never an authorization grant. example: "{request_id}" schema: type: string description: Nonempty identifier of the stored request resource. minLength: 1 maxLength: 256 TriggerWebhookId: name: webhook-id in: header required: true description: Opaque delivery ID. It remains stable across retries of the same event and can be used as an idempotency key. schema: type: string minLength: 1 example: msg_test_123 TriggerWebhookTimestamp: name: webhook-timestamp in: header required: true description: Unix time in seconds when this delivery attempt was signed. schema: type: integer format: int64 example: 1700000000 TriggerWebhookSignature: name: webhook-signature in: header required: true description: | `v1,` followed by the standard Base64-encoded HMAC-SHA256 digest. To verify it, remove the `whsec_` prefix from `signing_secret`, standard-Base64-decode the remainder, and use those bytes as the HMAC key. Sign the UTF-8 bytes of `webhook-id + "." + webhook-timestamp + "." + raw request body`. Verify the signature against the unmodified request body before parsing JSON, and use a constant-time comparison. Fixed test vector (the raw body is one line with no trailing newline): - decoded signing key bytes (UTF-8; test only): `test_webhook_signing_secret_1234` - `webhook-id`: `81e6dc877ac553ef96ecbc939c1e46431159491991ba55cd131fbd0e3746c6bc` - `webhook-timestamp`: `1700000000` - `raw request body`: `{"version":"1","trigger_id":"trigger_test_123","datasource":"GITHUB","reason":"REVIEW_REQUESTED","doc_type":"pull","event_type":"DOCUMENT_CHANGE","doc_id":"GITHUB_pull_123","view_url":"https://github.com/acme/payments-api/pull/123","title":"Add retry backoff to the crawler","event_time":"2025-04-23T11:00:00Z"}` - `webhook-signature`: `v1,JqvHW0dwAOSLndiwQdXLUS/P+2RvOO8x4sOWgA/w0Gs=` schema: type: string pattern: ^v1,[A-Za-z0-9+/=]+$ example: v1,xxx