> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lithoblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a queue

> A batching policy: events pushed to it are collected into batches and sent as one message per batch, aggregated by `aggregation_config`. The organization's tier caps how many active queues it may have and which execution modes it may use; the database enforces both and the message says which.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/queues
openapi: 3.0.0
info:
  version: 0.0.1
  title: LithoBlocks API
  description: >-

    # LithoBlocks API


    Welcome to the LithoBlocks API documentation. This API enables you to manage
    templates, entities, and organizations with a powerful, scope-based
    authorization system.


    ## API versioning


    Documented operations are under the `/v1` path prefix (for example, `GET
    /v1/templates`). **Older integrations** may still call the same routes
    without the `/v1` prefix (for example, `GET /templates`); those URLs remain
    supported for backward compatibility but are not listed in this OpenAPI
    document. **New integrations** should use `/v1` URLs.


    ## JSON and query naming


    Canonical names in JSON bodies, query strings, and path parameter names
    documented here are **snake_case** (for example `organization_id`,
    `template_id`, `include_author`). During a deprecation window, many inputs
    still accept legacy **camelCase** keys for the same values (for example
    `templateId` in place of `template_id`). **Responses** use snake_case for
    multi-word keys. Prefer snake_case for new clients; camelCase on input may
    be removed in a future version.


    ## Authentication & Authorization


    This API uses **LithoBlocks API Keys** for authentication with **scope-based
    authorization** for granular access control.


    ### Getting Your API Key


    1. **Log into your LithoBlocks organization dashboard**

    2. **Navigate to API Keys** in your account settings

    3. **Create a new API key** and select the required scopes

    4. **Copy your API key** (it will only be shown once for security)


    ### Using Your API Key


    Include your API key in the Authorization header:


    ```

    Authorization: Bearer lb_live_sk_example_key_here

    ```


    ### API Key Scopes & Role Requirements


    Your available scopes depend on your **organization role**. When creating an
    API key, you can only select scopes your role permits:


    Every operation below declares the scope it requires, and the API enforces
    exactly that scope. A key without it receives `403` with `required_scopes`
    in the body.


    #### 👥 **All Roles** (Viewer, Member, Admin, Owner)

    | Scope | Description |

    |-------|-------------|

    | `templates:read` | Read templates, search them, and read their versions |

    | `entities:read` | Read entities and their fields, and search them |

    | `organizations:read` | Read the organization and its member list |

    | `usage:read` | Read credit balance and usage |

    | `sample-data:read` | Read sample data |


    #### ✏️ **Member+** (Member, Admin, Owner)

    | Scope | Description |

    |-------|-------------|

    | `templates:create` | Create templates |

    | `templates:update` | Update templates and add versions |

    | `templates:activate` | Make a template version the active one |

    | `messages:create` | Compile templates and send messages |

    | `messages:preview` | Preview messages |

    | `entities:write` | Update and delete entities and their fields |


    #### 🔑 **Admin+** (Admin, Owner)

    | Scope | Description |

    |-------|-------------|

    | `templates:delete` | Delete templates |

    | `organizations:write` | Update the organization and invite members |

    | `users:read` | Read organization users by id |

    | `users:write` | Delete organization users |

    | `queues:write` | Push events to queue policies |


    `queues:read`, `scheduled:read` and `scheduled:write` exist so keys can be
    prepared for the scheduled messages and batch digests release; no operation
    requires them yet.


    ### API Key Management


    - **Multiple Keys**: Create multiple API keys with different scopes for
    different use cases

    - **Key Rotation**: Regularly rotate your API keys for security

    - **Scope Limitation**: Only request the minimum scopes needed for your
    application

    - **Organization Scoped**: All API keys are scoped to your organization


    ### Security Best Practices


    - **Never share API keys** or commit them to version control

    - **Use environment variables** to store API keys in your applications

    - **Create separate keys** for development, staging, and production

    - **Revoke unused keys** from your dashboard regularly


    ### Multi-Tenant Isolation


    All API endpoints enforce **organization-level isolation**:

    - You can only access resources within your organization

    - API keys are tied to the organization where they were created

    - Cross-organization access is never permitted


    ## Role-Based Access Control


    ### 👀 **Viewer Role**

    - Can read templates and entities

    - Can compile templates into messages

    - **Cannot** create or modify resources

    - **Cannot** access admin functions


    ### ✏️ **Member Role** 

    - All Viewer permissions

    - Can create and update templates

    - Can create and update entities

    - **Cannot** access admin functions


    ### 🔧 **Admin Role**

    - All Member permissions  

    - Can manage organization settings

    - Can view and manage users

    - **Cannot** delete the organization


    ### 👑 **Owner Role**

    - All Admin permissions

    - Full organization control

    - Can delete the organization

    - Can transfer ownership
                
  contact:
    name: LithoBlocks
    url: https://lithoblocks.com
    email: support@lithoblocks.com
servers:
  - url: https://api.lithoblocks.com
    description: Production (paths in this spec are rooted at /v1/...)
  - url: http://localhost:8787
    description: Local dev (paths in this spec are rooted at /v1/...)
security: []
paths:
  /v1/queues:
    post:
      tags:
        - Queues
      summary: Create a queue
      description: >-
        A batching policy: events pushed to it are collected into batches and
        sent as one message per batch, aggregated by `aggregation_config`. The
        organization's tier caps how many active queues it may have and which
        execution modes it may use; the database enforces both and the message
        says which.
      requestBody:
        description: The queue
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                description:
                  type: string
                  maxLength: 2000
                template_id:
                  type: string
                  format: uuid
                execution_mode:
                  type: string
                  enum:
                    - fixed_interval
                    - rolling_window
                    - fixed_volume
                execution_config:
                  type: object
                  additionalProperties:
                    type: integer
                    minimum: 0
                    exclusiveMinimum: true
                  description: >-
                    Canonical keys per execution_mode: fixed_interval → {
                    interval_minutes }; rolling_window → { window_minutes };
                    fixed_volume → { event_threshold, max_wait_minutes }
                destination:
                  anyOf:
                    - type: object
                      properties:
                        channel_id:
                          type: string
                      required:
                        - channel_id
                      additionalProperties: false
                    - type: object
                      properties:
                        recipient_email:
                          type: string
                          format: email
                      required:
                        - recipient_email
                      additionalProperties: false
                    - type: object
                      properties:
                        recipient_slack_id:
                          type: string
                      required:
                        - recipient_slack_id
                      additionalProperties: false
                aggregation_config:
                  type: object
                  properties:
                    item_mapping:
                      type: object
                      additionalProperties:
                        type: string
                        minLength: 1
                    aggregate_mapping:
                      type: object
                      additionalProperties:
                        type: object
                        properties:
                          strategy:
                            type: string
                            enum:
                              - first
                              - last
                              - min
                              - max
                              - sum
                              - count_events
                              - most_frequent
                              - any_true
                              - all_true
                          field:
                            type: string
                            minLength: 1
                          source:
                            type: string
                            minLength: 1
                        required:
                          - strategy
                      default: {}
                    items_key:
                      type: string
                      minLength: 1
                  required:
                    - item_mapping
                  description: >-
                    How the batch's events become one template `data`; omitted,
                    the template receives { items: [event, …] }
                credit_cost:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 1
                is_active:
                  type: boolean
                  default: true
              required:
                - name
                - template_id
                - execution_mode
                - execution_config
                - destination
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '400':
          description: >-
            execution_config has the wrong keys for its mode, or the database
            refused the row (`invalid_data`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: >-
            Insufficient permissions, or the organization's tier does not allow
            it (`tier_limit`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Template not found in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: The request body, query string or path parameters failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth:
            - queues:write
components:
  schemas:
    Queue:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        template_id:
          type: string
        template_version_id:
          type: string
          nullable: true
        execution_mode:
          type: string
          enum:
            - fixed_interval
            - rolling_window
            - fixed_volume
        execution_config:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
            exclusiveMinimum: true
          description: >-
            Canonical keys per execution_mode: fixed_interval → {
            interval_minutes }; rolling_window → { window_minutes };
            fixed_volume → { event_threshold, max_wait_minutes }
        destination:
          anyOf:
            - type: object
              properties:
                channel_id:
                  type: string
              required:
                - channel_id
              additionalProperties: false
            - type: object
              properties:
                recipient_email:
                  type: string
                  format: email
              required:
                - recipient_email
              additionalProperties: false
            - type: object
              properties:
                recipient_slack_id:
                  type: string
              required:
                - recipient_slack_id
              additionalProperties: false
            - nullable: true
        aggregation_config:
          type: object
          nullable: true
          properties:
            item_mapping:
              type: object
              additionalProperties:
                type: string
                minLength: 1
            aggregate_mapping:
              type: object
              additionalProperties:
                type: object
                properties:
                  strategy:
                    type: string
                    enum:
                      - first
                      - last
                      - min
                      - max
                      - sum
                      - count_events
                      - most_frequent
                      - any_true
                      - all_true
                  field:
                    type: string
                    minLength: 1
                  source:
                    type: string
                    minLength: 1
                required:
                  - strategy
              default: {}
            items_key:
              type: string
              minLength: 1
          required:
            - item_mapping
        credit_cost:
          type: integer
        is_active:
          type: boolean
        created_at:
          type: string
        updated_at:
          type: string
        pending_event_count:
          type: integer
          description: Events waiting in the open batch
        active_batch:
          $ref: '#/components/schemas/QueueBatch'
      required:
        - id
        - name
        - description
        - template_id
        - template_version_id
        - execution_mode
        - execution_config
        - destination
        - aggregation_config
        - credit_cost
        - is_active
        - created_at
        - updated_at
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Human-readable summary. Not stable; match on `code`.
        code:
          $ref: '#/components/schemas/ErrorCode'
        request_id:
          type: string
          description: >-
            Echoed from the request's X-Request-Id header, or generated. Quote
            it in support requests.
        message:
          type: string
        details:
          type: string
        error_details:
          type: string
        success:
          type: boolean
          enum:
            - false
        valid:
          type: boolean
          enum:
            - false
        required_scopes:
          type: array
          items:
            type: string
        user_scopes:
          type: array
          items:
            type: string
      required:
        - error
        - code
        - request_id
    ValidationError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            issues:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  path:
                    type: array
                    items:
                      anyOf:
                        - type: string
                        - type: number
                  message:
                    type: string
                required:
                  - code
                  - path
                  - message
            name:
              type: string
          required:
            - issues
            - name
        message:
          type: string
          description: >-
            The issues as one line, `path: message; path: message`, for callers
            that show a string (form builders such as Make)
        code:
          type: string
          enum:
            - validation_failed
        request_id:
          type: string
      required:
        - success
        - error
        - message
        - code
        - request_id
    QueueBatch:
      type: object
      nullable: true
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - collecting
            - ready
            - processing
            - sent
            - failed
        event_count:
          type: integer
        window_start:
          type: string
          nullable: true
        window_end:
          type: string
          nullable: true
        created_at:
          type: string
        processed_at:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
      required:
        - id
        - status
        - event_count
        - window_start
        - window_end
        - created_at
        - processed_at
        - error_message
    ErrorCode:
      type: string
      enum:
        - unauthenticated
        - invalid_token
        - insufficient_scope
        - access_denied
        - validation_failed
        - invalid_request
        - invalid_data
        - invalid_destination
        - invalid_search_query
        - not_found
        - template_not_found
        - version_not_found
        - organization_not_found
        - entity_not_found
        - field_not_found
        - user_not_found
        - profile_not_found
        - credits_not_found
        - insufficient_credits
        - overage_limit_exceeded
        - credit_deduction_failed
        - compilation_failed
        - no_blocks_to_send
        - slack_not_connected
        - slack_user_not_found
        - slack_dm_failed
        - slack_token_decrypt_failed
        - slack_api_error
        - already_exists
        - invitation_pending
        - idempotency_conflict
        - idempotency_in_progress
        - rate_limited
        - tier_limit
        - invalid_state
        - maintenance
        - misconfigured
        - internal_error
      description: >-
        Machine-readable reason for the failure. Match on this, not on `error`.
        New codes may be added; existing ones are stable.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        LithoBlocks API key obtained from your organization dashboard. The
        LithoBlocks MCP server also presents a Supabase-issued user session
        token here on the user's behalf; such a token acts as that user with the
        scopes their organization role allows.

````