ASAP Search API

openapi: 3.2.0
info:
  title: ASAP Platform Search API
  description: 'Public HTTP API for ASAP Platform (api.asap.cool).


    All `/v1` responses are wrapped in a standard envelope. Success responses are `{ "data": , "meta": { "request_id", "next_cursor"?, "has_more"? } }` — the schema documented for each operation describes the inner `data` value. Errors are `{ "error": { "code", "message", "field"?, "request_id" } }`. Every response also carries an `X-Request-Id` header matching `meta.request_id` / `error.request_id`.'
  license:
    name: BUSL-1.1
  version: 0.0.0
servers:
- url: https://api.asap.cool
  description: Production
tags:
- name: Search
  description: 'Cross-app search: one needle, results grouped by source, composed only from the apps the org can see.'
paths:
  /v1/search:
    get:
      tags:
      - Search
      summary: GET /v1/search
      operationId: searchEverything
      parameters:
      - name: q
        in: query
        description: What to look for, at least two characters.
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Hits per source, 1..=20 (defaults to 5).
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int32
          minimum: 0
      responses:
        '200':
          description: Hits grouped by source, composed only from the sources the org can see.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: No active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: Needle too short or invalid limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - session: []
components:
  schemas:
    ErrorBody:
      type: object
      description: 'Generic error body returned by API handlers when they fail. `code` is a

        stable machine-readable token; `message` is human-friendly and meant for

        surfacing to end users.'
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable machine token (e.g. `invalid_credentials`).
        field:
          type:
          - string
          - 'null'
          description: Offending request field for validation errors, when known.
        message:
          type: string
          description: Human-readable message.
    SearchResponse:
      type: object
      description: Grouped results.
      required:
      - groups
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/SearchGroupView'
          description: 'Groups, in source order, including the ones that matched nothing — a

            source searched without a hit is information the palette shows.'
    SearchGroupView:
      type: object
      description: One source's hits.
      required:
      - source
      - items
      - truncated
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SearchHitView'
          description: Hits, newest first.
        source:
          type: string
          description: '`contact`, `document`, `deal`, `envelope` or `file`.'
        truncated:
          type: boolean
          description: '`true` when the cap hid further matches.'
    SearchHitView:
      type: object
      description: One hit.
      required:
      - id
      - title
      - route
      properties:
        id:
          type: string
          format: uuid
          description: Id of the underlying row — unique within its source only.
        route:
          type: string
          description: 'SPA route that opens the hit, resolved server-side so no client needs

            its own URL plan.'
        subtitle:
          type:
          - string
          - 'null'
          description: Secondary label, when the source has one worth showing.
        title:
          type: string
          description: Primary label.
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
    session:
      type: apiKey
      in: cookie
      name: asap_session