openapi: 3.0.0
info:
  version: "2026-04-01"
  title: Glean Platform API
  x-source-commit-sha: 2e2d3269b7d70d7a987985956e264bfc087d1a0d
  x-open-api-commit-sha: 5dd85b126df60437ca4a2ba2061b79d4a7d3fe40
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-visibility: Public
      x-glean-experimental:
        id: 4abc1e17-8e06-490b-99a7-e8f97592405a
        introduced: "2026-05-12"
      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-visibility: Public
      x-glean-experimental:
        id: 009b3e94-694b-4deb-b80a-c67011173715
        introduced: "2026-05-12"
      parameters:
        - in: path
          name: agent_id
          description: ID of the agent to retrieve.
          required: true
          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-visibility: Public
      x-glean-experimental:
        id: b40b4dd3-3839-48e6-9e45-7e63e8148b49
        introduced: "2026-05-12"
      parameters:
        - in: path
          name: agent_id
          description: ID of the agent whose schemas should be retrieved.
          required: true
          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. Set `stream` to true to receive server-sent events; otherwise the response contains the final agent messages.
      operationId: platform-agents-create-run
      x-visibility: Public
      x-glean-experimental:
        id: 26bba669-2e92-4e5d-9798-6a532fae4e9f
        introduced: "2026-05-12"
      x-codegen-request-body-name: payload
      parameters:
        - in: path
          name: agent_id
          description: ID of the agent to run.
          required: true
          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.
                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"}]}]}
        "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: createRun
  /api/skills:
    get:
      tags:
        - Skills
      summary: List skills
      description: |
        List skills available to the authenticated user.
      operationId: platform-skills-list
      x-visibility: Public
      x-glean-experimental:
        id: 3eb65937-03a3-472b-9a00-be713f302b5f
        introduced: "2026-06-23"
      parameters:
        - in: query
          name: page_size
          description: Maximum number of skills to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - 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/{skill_id}:
    get:
      tags:
        - Skills
      summary: Retrieve skill
      description: |
        Retrieve metadata for a skill available to the authenticated user.
      operationId: platform-skills-get
      x-visibility: Public
      x-glean-experimental:
        id: 8f8d1c92-a484-4769-9903-200613dc8a72
        introduced: "2026-06-23"
      parameters:
        - name: skill_id
          in: path
          required: true
          description: Glean 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/search:
    post:
      tags:
        - Search
      summary: Search
      description: |
        Execute a search query and retrieve ranked results. This is the data retrieval variant of the search API and returns only results and pagination state.
      operationId: platform-search
      x-visibility: Public
      x-glean-experimental:
        id: 5ab612fc-ed50-4419-bec3-e5fe83934653
        introduced: "2026-04-08"
      x-codegen-request-body-name: payload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PlatformSearchRequest"
      responses:
        "200":
          description: Successful search.
          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"
        "429":
          $ref: "#/components/responses/PlatformTooManyRequests"
        "500":
          $ref: "#/components/responses/PlatformInternalServerError"
        "503":
          $ref: "#/components/responses/PlatformServiceUnavailable"
      x-speakeasy-group: search
      x-speakeasy-name-override: query
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:
    PlatformAgentsSearchRequest:
      type: object
      additionalProperties: false
      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
        - resource_not_found
        - method_not_allowed
        - request_timeout
        - request_too_large
        - conflict
        - gone
        - unprocessable_query
        - 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
        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
        conflict:
          status: 409
          title: Conflict
        gone:
          status: 410
          title: Gone
        unprocessable_query:
          status: 422
          title: Unprocessable Query
        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
    PlatformMessageTextBlock:
      type: object
      required:
        - text
        - type
      properties:
        text:
          type: string
          description: Text content.
        type:
          $ref: "#/components/schemas/PlatformContentType"
    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).
      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.
          default: false
    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.
    PlatformSkillStatus:
      type: string
      enum:
        - DRAFT
        - ENABLED
        - DISABLED
      description: Current skill status.
    PlatformSkillOrigin:
      type: string
      enum:
        - CUSTOM
      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:
        - id
        - display_name
        - description
        - latest_version
        - latest_minor_version
        - status
        - origin
        - owner
        - created_at
        - updated_at
      properties:
        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:
        - skills
        - has_more
        - next_cursor
        - request_id
      properties:
        skills:
          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
          nullable: true
          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.
    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.
    PlatformFilterOperator:
      type: string
      description: Supported filter operator.
      enum:
        - EQUALS
        - NOT_EQUALS
        - GT
        - GTE
        - LT
        - LTE
    PlatformFilter:
      type: object
      required:
        - field
        - values
      description: |
        A single filter criterion. For `EQUALS`, multiple values within a filter are OR'd. For `NOT_EQUALS`, multiple values exclude all listed values. Filters are AND'd with each other and with any inline query operators.
      properties:
        field:
          type: string
          description: |
            The field to filter on. Accepts built-in filter field names such as `type`, `owner`, `from`, `author`, `channel`, `status`, `assignee`, `reporter`, `component`, `mentions`, and `collection`, plus custom datasource property names.
          example: type
        values:
          type: array
          minItems: 1
          items:
            type: string
          description: One or more values to match.
          example:
            - spreadsheet
            - presentation
        operator:
          allOf:
            - $ref: "#/components/schemas/PlatformFilterOperator"
          description: |
            Comparison operator to apply to this filter. Defaults to `EQUALS`. `GT`, `GTE`, `LT`, and `LTE` range operators require exactly one value; express bounded ranges with multiple filters on the same field.
    PlatformTimeRange:
      type: object
      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
        datasources:
          - confluence
          - google_drive
        filters:
          - field: type
            values:
              - spreadsheet
              - presentation
      properties:
        query:
          type: string
          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
          nullable: true
          description: |
            Opaque pagination token from a previous response's `next_cursor` field. Omit on the first request.
        datasources:
          type: array
          items:
            type: string
          description: |
            Restrict results to specific datasources. Requests must not specify both `datasources` and `datasource_instances`.
        datasource_instances:
          type: array
          items:
            type: string
          description: |
            Restrict results to specific datasource instances. Values are datasource instance identifiers returned by `GET /api/search/filters`. Requests must not specify both `datasources` and `datasource_instances`.
        filters:
          type: array
          items:
            $ref: "#/components/schemas/PlatformFilter"
          description: |
            Structured filters applied to search results. Equality operators OR multiple values within a filter. Multiple filters are AND'd together, including range filters on the same field. Filters are AND'd with any inline operators in `query`. Note that conflicting constraints on the same field (e.g., `type:document` in the query and `type: spreadsheet` in a filter) produce an empty result set.
        time_range:
          $ref: "#/components/schemas/PlatformTimeRange"
    PlatformResult:
      type: object
      required:
        - url
        - title
        - datasource
      properties:
        url:
          type: string
          format: uri
          description: Canonical URL of the result.
          example: https://company.atlassian.net/wiki/spaces/ENG/pages/12345
        title:
          type: string
          description: Result title.
          example: Q2 2026 Platform Roadmap
        snippets:
          type: array
          items:
            type: string
          description: Query-relevant plain-text excerpts from the result body.
          example:
            - The platform team will focus on API stability and...
        datasource:
          type: string
          description: The datasource this result originates from.
          example: confluence
        datasource_instance:
          type: string
          nullable: true
          description: The datasource instance this result originates from, if known.
          example: confluence_acme
        document_type:
          type: string
          nullable: true
          description: The document type within the datasource.
          example: page
        creator:
          $ref: "#/components/schemas/PlatformPersonReference"
        owner:
          $ref: "#/components/schemas/PlatformPersonReference"
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: When the result was last modified.
        created_at:
          type: string
          format: date-time
          nullable: true
          description: When the result was created.
    PlatformSearchResponse:
      type: object
      required:
        - results
        - has_more
        - next_cursor
        - request_id
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/PlatformResult"
          description: Ordered list of search results.
        has_more:
          type: boolean
          description: Indicates whether additional pages of results are available.
        next_cursor:
          type: string
          nullable: true
          description: Opaque token to pass as `cursor` in the next request.
        request_id:
          type: string
          description: Platform-generated request ID for support correlation.
  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"