Flowral Workspace API

openapi: 3.2.0
info:
  title: Flowral Workspace 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: Workspace
  description: Who the credential is.
paths:
  /v1/me:
    get:
      operationId: workspace.context
      summary: Who this credential is
      description: 'The workspace, the credential''s role and scopes, and the plan. Cheap, and the right health check for an integration. For a person-token (authorization_code), also includes `userId` — the same id `GET /team/members` lists them under, for a client that wants "assign to me"/"my work" to work without asking the person to pick themselves out of their own team — and `orgs`: every workspace they belong to, for a client that wants to offer a "switch workspace" action (see POST /oauth/token''s refresh_token grant). Unlike every other /v1 route, this one is NOT refused on a Free-plan workspace — it reports `plan: "free"` truthfully instead, which is what lets a client explain the refusal (or, for a person-token, offer switching to a different workspace) rather than just receiving one.'
      tags:
      - Workspace
      responses:
        '200':
          description: SUCCESS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Context'
        '401':
          description: UNAUTHORIZED · CREDENTIAL_REVOKED
          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: []
      x-codeSamples:
      - lang: cURL
        source: "curl '{{API_URL}}/v1/me' \\\n  -H 'Authorization: Bearer {{API_KEY}}'"
      x-examples:
      - request:
          curl: "curl '{{API_URL}}/v1/me' \\\n  -H 'Authorization: Bearer {{API_KEY}}'"
        response:
          status: 200
          body:
            workspaceId: org_5c1
            workspaceName: Acme Studio
            credentialId: key_8fd2
            credentialName: Acme CI
            role: member
            scopes:
            - flows:read
            - flows:write
            - work:write
            plan: pro
components:
  schemas:
    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
    Context:
      type: object
      description: Who the credential is and what it may do — the first call to make when wiring an integration.
      properties:
        workspaceId:
          type: string
        workspaceName:
          type: string
        credentialId:
          type: string
          description: The key or client this token belongs to.
        credentialName:
          type: string
          examples:
          - Acme CI
        role:
          type: string
          enum:
          - admin
          - member
          - viewer
          description: The credential’s role in the workspace. It decides what every other call may do.
        scopes:
          type: array
          items:
            type: string
        plan:
          type: string
          enum:
          - free
          - pro
      required:
      - workspaceId
      - workspaceName
      - role
      - scopes
      - plan
  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