Flowral Search API

openapi: 3.2.0
info:
  title: Flowral Search API
  version: 1.0.0
  summary: Client projects as dependency graphs — over HTTP.
  description: 'The Flowral public API: flows, the tasks in them, and the derived state that

    makes a dependency planner useful — what is ready, what is blocked, and when a

    project actually lands.


    **Authentication.** Every request carries a credential created in the app under

    **API & AI**. Either send an API key as a bearer token, or exchange a client id

    and secret for a short-lived token at `POST /v1/oauth/token`. A credential

    belongs to a workspace and carries its own role: it can never do more than that

    role allows, and it cannot move between workspaces.


    **Errors** are `{ "error": { "code", "message" } }`. Switch on `code`; the

    message is for humans and may change.


    **Lists** are `{ "total", "items" }` and take `size` and `from`.


    **Rate limit** 120 requests/minute per credential, burst 240. Exceeding it

    returns `429` with `Retry-After`.


    **Stability.** This is v1. Fields get added; nothing that exists is removed or

    repurposed without a new major version. The platform API the web app uses is a

    different, unversioned surface — it is not this, and it will change without

    notice.'
  contact:
    name: Flowral
    email: hello@flowral.app
    url: https://flowral.app/api
  license:
    name: Proprietary
    url: https://flowral.app/terms
servers:
- url: https://api.flowral.app
  description: Production
security:
- apiKey: []
- oauth2: []
tags:
- name: Search
  description: Finding things by name.
paths:
  /v1/search:
    get:
      operationId: search
      summary: Search the workspace
      description: Flows, tasks and templates matching a query — for a picker, or to resolve a name a human typed into an id.
      tags:
      - Search
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: '`flow`, `task` or `template`. Omit for all three.'
        schema:
          type: string
          description: '`flow`, `task` or `template`. Omit for all three.'
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: SUCCESS
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total matching, not the length of `items`.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'
                required:
                - total
                - items
        '400':
          description: VALIDATION_FAILED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: VALIDATION_FAILED
                  message: Human-readable explanation.
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Human-readable explanation.
        '403':
          description: FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Human-readable explanation.
        '429':
          description: RATE_LIMITED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: RATE_LIMITED
                  message: Human-readable explanation.
      security:
      - apiKey: []
      - oauth2:
        - flows:read
components:
  schemas:
    SearchResult:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - flow
          - task
          - template
        title:
          type: string
        flowId:
          type:
          - string
          - 'null'
        url:
          type: string
          description: Where it lives in the app, for a link back.
      required:
      - id
      - type
      - title
    Error:
      type: object
      description: Every non-2xx response has this shape.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Stable, machine-readable. Switch on this, not on the message.
              examples:
              - NOT_FOUND
            message:
              type: string
              description: Human-readable. May change; never parse it.
            details:
              type: object
              additionalProperties: true
              description: Present when the code alone is not actionable — which task blocked, which deliverable is missing, which limit was hit.
          required:
          - code
          - message
      required:
      - error
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An API key from the app: `Authorization: Bearer fl_sk_live_…`.'
    oauth2:
      type: oauth2
      description: Client credentials, for anything long-lived.
      flows:
        clientCredentials:
          tokenUrl: https://api.flowral.app/v1/oauth/token
          scopes:
            flows:read: Read flows, tasks, schedules and reports
            flows:write: Create and change flows and tasks
            work:write: Start, complete, assign and comment on work
            team:read: Read members and invitations
            team:write: Invite people and change roles
            templates:read: Read templates and start flows from them
            notifications:read: Read what people are emailed about
            notifications:write: Change what people are emailed about