Flowral Templates API

openapi: 3.2.0
info:
  title: Flowral Templates 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: Templates
  description: Saved flow shapes.
paths:
  /v1/templates:
    get:
      operationId: templates.list
      summary: List templates
      description: Saved flow shapes in this workspace.
      tags:
      - Templates
      parameters:
      - name: category
        in: query
        required: false
        schema:
          type: string
      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/Template'
                required:
                - total
                - items
        '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:
        - templates:read
  /v1/templates/{templateId}:
    get:
      operationId: templates.get
      summary: Get a template
      description: The template with the task graph it will produce, so an integration can show what it is about to create.
      tags:
      - Templates
      parameters:
      - name: templateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: SUCCESS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '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.
        '404':
          description: NOT_FOUND
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  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:
        - templates:read
  /v1/templates/{templateId}/flows:
    post:
      operationId: templates.use
      summary: Start a flow from a template
      description: Creates a new flow from the template and returns it, graph and all. Using a template is available on every plan; saving new ones is not.
      tags:
      - Templates
      parameters:
      - name: templateId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Defaults to the template's name.
                dueDate:
                  type: string
                  description: ISO 8601.
      responses:
        '201':
          description: CREATED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Flow'
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Human-readable explanation.
        '403':
          description: FORBIDDEN · SUBSCRIPTION_PAST_DUE
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Human-readable explanation.
        '404':
          description: NOT_FOUND
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  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:write
        - templates:read
      x-minRole: member
components:
  schemas:
    Task:
      type: object
      description: 'A unit of work in a flow. Tasks are joined by dependencies: one is ready only when everything it depends on is done, and one with sub-tasks completes through them.'
      properties:
        id:
          type: string
          examples:
          - tsk_9f2c41
        flowId:
          type: string
        parentId:
          type:
          - string
          - 'null'
          description: Set when this is a sub-task — the objective it belongs to. Null for an objective itself.
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - blocked
          - ready
          - in_progress
          - done
          description: Derived from the graph on read, never stored. Work moves ready → in_progress → done; nothing jumps straight to done.
        dependsOn:
          type: array
          items:
            type: string
          description: Task ids that must be done first.
        blockedBy:
          type: array
          items:
            type: string
          description: Of those, the ones not yet done. Empty when status is not "blocked".
        assigneeId:
          type:
          - string
          - 'null'
        estimateHours:
          type:
          - number
          - 'null'
        criticalPath:
          type: boolean
          description: True when this task is on the chain that decides the flow's finish date.
        subtasks:
          type: array
          items:
            $ref: '#/components/schemas/SubTask'
        requiredDeliverables:
          type: array
          description: Files that have to be handed in before the task can complete.
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              satisfied:
                type: boolean
      required:
      - id
      - flowId
      - parentId
      - name
      - status
      - dependsOn
    FlowSummary:
      type: object
      description: A flow without its tasks — what list endpoints return.
      properties:
        id:
          type: string
          examples:
          - flw_2b8e10
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        archived:
          type: boolean
        public:
          type: boolean
          description: Whether this flow is published — readable by anyone with its link, with no account. Assignees, comments and files are never included in the public view.
        publicUrl:
          type:
          - string
          - 'null'
          description: The published link, or null when the flow is private.
          examples:
          - https://platform.flowral.app/public/flow/flw_2b8e10
        dueDate:
          type: string
          format: date-time
          description: The date the flow is meant to land, if one is set.
        taskCount:
          type: integer
        doneCount:
          type: integer
        readyCount:
          type: integer
          description: Tasks that can be started right now.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - archived
    Flow:
      allOf:
      - $ref: '#/components/schemas/FlowSummary'
      - type: object
        properties:
          tasks:
            type: array
            items:
              $ref: '#/components/schemas/Task'
        required:
        - tasks
      description: A flow with its full task graph and derived state.
    Template:
      type: object
      description: A saved flow shape, ready to start a new flow from.
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        category:
          type:
          - string
          - 'null'
        taskCount:
          type: integer
        usedCount:
          type: integer
      required:
      - id
      - name
    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
    SubTask:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        done:
          type: boolean
        assigneeId:
          type:
          - string
          - 'null'
          description: Workspace member id.
        estimateHours:
          type:
          - number
          - 'null'
      required:
      - id
      - name
      - done
  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