openapi: 3.0.0
info:
  title: SyncDocs Admin API
  version: 1.0.0
  license:
    name: Proprietary
    url: https://syncdocs.ai/tos
  description: >2-
     # SyncDocs Admin API
    Complete enterprise content management system (ECM) core APIs for accessing
    ECM functionality programmatically.

    ## Architecture Overview

    When you start with Sync, you are assigned an **Account** with a unique ID.
    Each account can have:

    - **Dataspaces**: Fully isolated data segments within an account, similar to
    separate databases. Each dataspace is used to isolate different business use
    cases within a single enterprise. - **Workspaces**: Virtual computing
    resources for storing, retrieving and manipulating content (managed
    separately via Workspace APIs) - **Libraries**: External content sources
    that can be scraped and indexed for use as citation sources in AI queries -
    **Users and Agents**: Can interact with Dataspaces/Workspaces with assigned
    roles - **Ontologies**: Define how content is organized within dataspaces

    ## Dataspace Resources

    Each Dataspace contains: - A unique **Ontology** that defines the
    business-purpose categorization and metadata structure - **Categories**:
    Represent the grouping or classification of content (taxonomy) - **Metadata
    Queries**: Specific metadata fields that can be associated with content and
    bound to categories - A collection of **Content** and **Projects** (managed
    via Workspace APIs)

    ## Metadata Query Binding

    Metadata Queries can be bound to Categories to indicate required attributes
    for content in that category. When binding, you can specify: - Whether the
    attribute is required/mandatory for every Content item in that category -
    Whether the attribute should be part of the Unique Index (content with same
    unique index values are considered versions of the same content)

    ## Authentication

    All endpoints require authentication using a bearer token and a valid
    account ID. 
servers:
  - url: https://cloud.syncdocs.ai/api
    description: Production - Sync Cloud Admin Services
  - url: /api
    description: Development server
tags:
  - name: Accounts
    description: >-
      Account management operations. Each account represents a unique enterprise
      customer with isolated resources.
  - name: Dataspaces
    description: >-
      Dataspace management operations. Dataspaces are fully isolated data
      segments within an account, similar to separate databases for different
      business use cases.
  - name: Workspaces
    description: >-
      Workspace management operations. Workspaces are virtual computing
      resources that provide stateless computational services for content
      processing.
  - name: Ontologies
    description: >-
      Ontology management operations. Ontologies define the categorization,
      indexing and metadata tagging structure for content within dataspaces.
  - name: Categories
    description: >-
      Category management operations. Categories represent the grouping or
      classification of content within a dataspace (taxonomy).
  - name: Metadata Queries
    description: >-
      Metadata key management operations. Metadata keys define specific metadata
      fields that can be associated with content and bound to categories.
  - name: Users
    description: >-
      User management operations. Users can interact with dataspaces and
      workspaces with assigned roles and permissions.
  - name: Libraries
    description: >-
      Library management operations. Libraries are external content sources that
      can be scraped and indexed for use as citation sources in AI queries.
  - name: Library Bindings
    description: >-
      Library binding operations. Bind libraries to workspaces to enable access
      to library content for AI queries.
  - name: Agents
    description: >-
      Agent management operations. Agents are automated entities that can
      perform operations on behalf of users.
  - name: Workflows
    description: >-
      Workflow management operations. Workflows define automated processes for
      content handling and business logic.
  - name: Task Definitions
    description: Task definition management operations
  - name: Helpers
    description: Helper utility operations
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CreateDataspace:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the dataspace
          example: Research Project Dataspace
        description:
          type: string
          minLength: 1
          description: Description of the dataspace
          example: A dataspace for organizing research documents
        ontologyId:
          type: string
          format: uuid
          description: UUID of the ontology
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      required:
        - name
        - description
        - ontologyId
      description: Data for creating a new dataspace
    UpdateDataspace:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the dataspace
          example: Updated Research Project Dataspace
        description:
          type: string
          minLength: 1
          description: Description of the dataspace
          example: Updated description for research documents dataspace
      description: Data for updating an existing dataspace
    Dataspace:
      type: object
      properties:
        id:
          type: string
          pattern: ^sds-[a-z0-9]{8}$
          description: Short dataspace ID with sds- prefix
          example: sds-a1b2c3d4
        name:
          type: string
          example: Research Project Dataspace
        description:
          type: string
          example: A dataspace for organizing research documents
        ontologyId:
          type: string
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
      required:
        - id
        - name
        - description
        - ontologyId
        - createdAt
      description: Representation of a dataspace
    DataspaceResponse:
      type: object
      properties:
        id:
          type: string
          pattern: ^sds-[a-z0-9]{8}$
          description: Short dataspace ID with sds- prefix
          example: sds-a1b2c3d4
        name:
          type: string
          example: Research Project Dataspace
        description:
          type: string
          example: A dataspace for organizing research documents
        accountId:
          type: string
          pattern: ^scd-[a-z0-9]{8}$
          description: Short account ID with scd- prefix
          example: scd-k2j8n4m1
        ontologyId:
          type: string
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
      required:
        - id
        - name
        - description
        - accountId
        - ontologyId
        - createdAt
      description: Response after successfully creating a dataspace
    CreateAccount:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the account
          example: Acme Corporation
        id:
          type: string
          pattern: ^scd-[a-z0-9]{8}$
          description: >-
            Optional custom account ID (must start with 'scd-' and be exactly 12
            characters total)
          example: scd-dev00001
      required:
        - name
      description: Data for creating a new account
    UpdateAccount:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the account
          example: Updated Acme Corporation
      required:
        - name
      description: Data for updating an account
    Account:
      type: object
      properties:
        id:
          type: string
          pattern: ^scd-[a-z0-9]{8}$
          description: Short account ID with scd- prefix
          example: scd-k2j8n4m1
        name:
          type: string
          example: Acme Corporation
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          nullable: true
          format: date-time
          example: '2024-01-15T14:30:00Z'
      required:
        - id
        - name
        - createdAt
        - updatedAt
      description: Representation of an account
    CreateWorkspace:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Name of the workspace
          example: Research Workspace
        description:
          type: string
          minLength: 1
          description: Description of the workspace
          example: A workspace for managing research documents and data
      required:
        - name
        - description
      description: Input for creating a new workspace
    UpdateWorkspace:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Name of the workspace
          example: Updated Research Workspace
        description:
          type: string
          minLength: 1
          description: Description of the workspace
          example: Updated description for research workspace
      description: Input for updating a workspace
    Workspace:
      type: object
      properties:
        id:
          type: string
          pattern: ^sws-[a-z0-9]{8}$
          description: Short workspace ID with sws- prefix
          example: sws-x9p3q7r5
        name:
          type: string
          example: Research Workspace
        description:
          type: string
          example: A workspace for managing research documents and data
        plan:
          type: string
          description: AWS region where the workspace is deployed
          example: us-east-2
        accountId:
          type: string
          pattern: ^scd-[a-z0-9]{8}$
          description: Account ID
          example: scd-k2j8n4m1
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          nullable: true
          format: date-time
          example: '2024-01-15T14:30:00Z'
      required:
        - id
        - name
        - description
        - plan
        - accountId
        - createdAt
        - updatedAt
      description: Representation of a workspace
    CreateOntology:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the ontology
          example: Research Document Ontology
        description:
          type: string
          minLength: 1
          description: Description of the ontology
          example: An ontology for classifying research documents
      required:
        - name
        - description
      description: Data for creating a new ontology
    UpdateOntology:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the ontology
          example: Updated Research Document Ontology
        description:
          type: string
          minLength: 1
          description: Description of the ontology
          example: Updated description for research document classification
      description: Data for updating an ontology
    Ontology:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174001
        name:
          type: string
          example: Research Document Ontology
        description:
          type: string
          example: An ontology for classifying research documents
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          nullable: true
          format: date-time
          example: '2024-01-15T14:30:00Z'
      required:
        - id
        - name
        - description
        - createdAt
        - updatedAt
      description: Representation of an ontology
    CreateCategory:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the category
          example: Research Papers
        description:
          type: string
          minLength: 1
          description: Description of the category
          example: Academic research papers and publications
        instructions:
          type: string
          nullable: true
          description: Instructions for this category
          example: Please ensure all papers include proper citations
      required:
        - name
        - description
      description: Data for creating a new category
    UpdateCategory:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the category
          example: Updated Research Papers
        description:
          type: string
          minLength: 1
          description: Description of the category
          example: Updated description for academic research papers
        instructions:
          type: string
          nullable: true
          description: Instructions for this category
          example: Updated instructions for paper categorization
      description: Data for updating a category
    Category:
      type: object
      properties:
        id:
          type: string
          example: cat-123abc45
        name:
          type: string
          example: Research Papers
        description:
          type: string
          example: Academic research papers and publications
        instructions:
          type: string
          nullable: true
          example: Please ensure all papers include proper citations
        ontologyId:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174001
        boundMetadataQueries:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                example: 123e4567-e89b-12d3-a456-426614174001
              name:
                type: string
                example: Author Name
              description:
                type: string
                nullable: true
                example: The name of the document author
              dataType:
                type: string
                enum:
                  - STRING
                  - SHORT_STRING
                  - NUMBER
                  - BOOLEAN
                  - DATE
                example: STRING
              instructions:
                type: string
                example: >-
                  Extract the full name of the primary author from the document
                  header or byline
              ontologyId:
                type: string
                format: uuid
                example: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
              createdAt:
                type: string
                format: date-time
                example: '2024-01-15T10:30:00Z'
              updatedAt:
                type: string
                nullable: true
                format: date-time
                example: '2024-01-15T14:30:00Z'
              binding:
                type: object
                properties:
                  required:
                    type: boolean
                    description: Whether this metadata query is required for this category
                    example: true
                  uniqueIndexElement:
                    type: boolean
                    description: >-
                      Whether this metadata query is part of the unique index
                      for this category
                    example: false
                required:
                  - required
                  - uniqueIndexElement
                description: Binding properties for this metadata query in this category
            required:
              - id
              - name
              - description
              - dataType
              - instructions
              - ontologyId
              - createdAt
              - updatedAt
              - binding
            description: Metadata key with its binding properties for this category
          description: Metadata keys bound to this category with their binding properties
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          nullable: true
          format: date-time
          example: '2024-01-15T14:30:00Z'
      required:
        - id
        - name
        - description
        - instructions
        - ontologyId
        - boundMetadataQueries
        - createdAt
        - updatedAt
      description: Representation of a category with bound metadata queries
    CreateMetadataQuery:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the metadata query
          example: Author Name
        description:
          type: string
          description: Description of the metadata query
          example: The name of the document author
        dataType:
          type: string
          enum:
            - STRING
            - SHORT_STRING
            - NUMBER
            - BOOLEAN
            - DATE
          description: Data type of the metadata query
          example: STRING
        instructions:
          type: string
          minLength: 1
          description: Instructions for how to execute the metadata query
          example: >-
            Extract the full name of the primary author from the document header
            or byline
      required:
        - name
        - dataType
        - instructions
      description: Data for creating a new metadata query
    UpdateMetadataQuery:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the metadata query
          example: Updated Author Name
        description:
          type: string
          description: Description of the metadata query
          example: Updated description of the author field
        dataType:
          type: string
          enum:
            - STRING
            - SHORT_STRING
            - NUMBER
            - BOOLEAN
            - DATE
          description: Data type of the metadata query
          example: STRING
        instructions:
          type: string
          minLength: 1
          description: Instructions for how to execute the metadata query
          example: >-
            Extract the full name of the primary author from the document header
            or byline
      description: Data for updating a metadata query
    MetadataQuery:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174001
        name:
          type: string
          example: Author Name
        description:
          type: string
          nullable: true
          example: The name of the document author
        dataType:
          type: string
          enum:
            - STRING
            - SHORT_STRING
            - NUMBER
            - BOOLEAN
            - DATE
          example: STRING
        instructions:
          type: string
          example: >-
            Extract the full name of the primary author from the document header
            or byline
        ontologyId:
          type: string
          format: uuid
          example: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          nullable: true
          format: date-time
          example: '2024-01-15T14:30:00Z'
      required:
        - id
        - name
        - description
        - dataType
        - instructions
        - ontologyId
        - createdAt
        - updatedAt
      description: Representation of a metadata query
    BindMetadataQuery:
      type: object
      properties:
        uniqueIndexElement:
          type: boolean
          description: Whether this metadata query is part of the unique index
          example: false
        required:
          type: boolean
          default: false
          description: Whether this metadata query is required
          example: true
      description: Data for binding a metadata query to a category
    CreateUser:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address of the user
          example: john.doe@example.com
        name:
          type: string
          minLength: 1
          description: Name of the user
          example: John Doe
        roles:
          type: array
          items:
            type: string
          description: Roles assigned to the user
        permissions:
          type: array
          items:
            type: string
          description: Permissions assigned to the user
      required:
        - email
        - name
      description: Data for creating a new user
    UpdateUser:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address of the user
          example: john.updated@example.com
        name:
          type: string
          minLength: 1
          description: Name of the user
          example: John Updated
        roles:
          type: array
          items:
            type: string
          description: Roles assigned to the user
        permissions:
          type: array
          items:
            type: string
          description: Permissions assigned to the user
      description: Data for updating a user
    User:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address of the user
          example: john.doe@example.com
        name:
          type: string
          minLength: 1
          description: Name of the user
          example: John Doe
        roles:
          type: array
          items:
            type: string
          description: Roles assigned to the user
        permissions:
          type: array
          items:
            type: string
          description: Permissions assigned to the user
        id:
          type: string
          format: uuid
          description: The ID of the user
          example: 123e4567-e89b-12d3-a456-426614174001
        clerkUserId:
          type: string
          description: Clerk user ID for authentication
          example: user_2Xxxx...
        lastLoginAt:
          type: string
          nullable: true
          format: date-time
          description: Last login timestamp
          example: '2024-01-15T14:30:00Z'
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          nullable: true
          format: date-time
          example: '2024-01-15T14:30:00Z'
        accountId:
          type: string
          pattern: ^scd-[a-z0-9]{8}$
          description: Short account ID with scd- prefix (from entitlements)
          example: scd-k2j8n4m1
      required:
        - email
        - name
        - id
        - createdAt
        - updatedAt
        - accountId
      description: A user in the system with account context
    CreateLibrary:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the library
          example: Research Library
        rootUrl:
          type: string
          format: uri
          description: Root URL of the library
          example: https://library.example.com
        urlFilter:
          type: string
          description: >-
            Regular expression to filter URLs when building the library. If not
            provided, uses rootUrl as prefix
          example: https://library\.example\.com/docs/.*
      required:
        - name
        - rootUrl
      description: Data for creating a new library
    UpdateLibrary:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name of the library
          example: Updated Research Library
        rootUrl:
          type: string
          format: uri
          description: Root URL of the library
          example: https://updated-library.example.com
        urlFilter:
          type: string
          nullable: true
          description: >-
            Regular expression to filter URLs when building the library. If not
            provided, uses rootUrl as prefix
          example: https://updated-library\.example\.com/docs/.*
      description: Data for updating a library
    Library:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174001
        name:
          type: string
          example: Research Library
        rootUrl:
          type: string
          format: uri
          example: https://library.example.com
        urlFilter:
          type: string
          nullable: true
          description: >-
            Regular expression to filter URLs when building the library. If not
            provided, uses rootUrl as prefix
          example: https://library\.example\.com/docs/.*
        accountId:
          type: string
          pattern: ^scd-[a-z0-9]{8}$
          example: scd-k2j8n4m1
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          nullable: true
          format: date-time
          example: '2024-01-15T14:30:00Z'
      required:
        - id
        - name
        - rootUrl
        - accountId
        - createdAt
        - updatedAt
      description: Representation of a library
    BoundLibrary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174001
        name:
          type: string
          example: Research Library
        rootUrl:
          type: string
          format: uri
          example: https://library.example.com
        urlFilter:
          type: string
          nullable: true
          description: >-
            Regular expression to filter URLs when building the library. If not
            provided, uses rootUrl as prefix
          example: https://library\.example\.com/docs/.*
        accountId:
          type: string
          pattern: ^scd-[a-z0-9]{8}$
          example: scd-k2j8n4m1
        createdAt:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          nullable: true
          format: date-time
          example: '2024-01-15T14:30:00Z'
        binding:
          type: object
          properties:
            createdAt:
              type: string
              format: date-time
              description: When this library was bound to the workspace
              example: '2024-01-15T10:30:00Z'
          required:
            - createdAt
          description: Binding properties for this library in this workspace
      required:
        - id
        - name
        - rootUrl
        - accountId
        - createdAt
        - updatedAt
        - binding
      description: Library with its binding properties for a workspace
    BindLibrary:
      type: object
      properties:
        libraryId:
          type: string
          format: uuid
          description: The ID of the library to bind to the workspace
          example: 123e4567-e89b-12d3-a456-426614174001
      required:
        - libraryId
      description: Data for binding a library to a workspace
    LibraryBinding:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: When this library was bound to the workspace
          example: '2024-01-15T10:30:00Z'
      required:
        - createdAt
      description: Binding properties for a library within a workspace
  parameters: {}
paths:
  /accounts/{accountId}/dataspaces:
    post:
      operationId: createDataspace
      tags:
        - Dataspaces
      summary: Create a new dataspace
      description: Create a new dataspace in an account. Requires authentication.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataspace'
      responses:
        '201':
          description: Dataspace created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataspaceResponse'
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
    get:
      operationId: listDataspaces
      tags:
        - Dataspaces
      summary: List all dataspaces for an account
      description: List all dataspaces in an account. Requires authentication.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '200':
          description: List of dataspaces
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dataspace'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
  /accounts/{accountId}/dataspaces/{dataspaceId}:
    get:
      operationId: getDataspace
      tags:
        - Dataspaces
      summary: Get a dataspace by ID
      description: Get details of a specific dataspace. Requires authentication.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            pattern: ^sds-[a-z0-9]{8}$
            description: Short dataspace ID with sds- prefix
            example: sds-a1b2c3d4
          required: true
          description: Short dataspace ID with sds- prefix
          name: dataspaceId
          in: path
      responses:
        '200':
          description: Dataspace details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataspace'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '404':
          description: Dataspace not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
    put:
      operationId: updateDataspace
      tags:
        - Dataspaces
      summary: Update a dataspace
      description: Update details of a specific dataspace. Requires authentication.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            pattern: ^sds-[a-z0-9]{8}$
            description: Short dataspace ID with sds- prefix
            example: sds-a1b2c3d4
          required: true
          description: Short dataspace ID with sds- prefix
          name: dataspaceId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDataspace'
      responses:
        '200':
          description: Dataspace updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataspace'
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '404':
          description: Dataspace not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
    delete:
      operationId: deleteDataspace
      tags:
        - Dataspaces
      summary: Delete a dataspace
      description: Delete a specific dataspace. Requires authentication.
      security:
        - bearerAuth: []
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            pattern: ^sds-[a-z0-9]{8}$
            description: Short dataspace ID with sds- prefix
            example: sds-a1b2c3d4
          required: true
          description: Short dataspace ID with sds- prefix
          name: dataspaceId
          in: path
      responses:
        '204':
          description: Dataspace deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
        '404':
          description: Dataspace not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An error occurred
                required:
                  - error
                description: Error response
  /accounts/{accountId}/ontologies/{ontologyId}/metadata-queries:
    post:
      operationId: createMetadataQuery
      tags:
        - Metadata Queries
      summary: Create a new metadata query
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMetadataQuery'
      responses:
        '201':
          description: Metadata key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataQuery'
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Ontology not found
    get:
      operationId: listMetadataQueries
      tags:
        - Metadata Queries
      summary: List all metadata queries in an ontology
      description: >-
        Returns all metadata queries with their category bindings including
        binding properties (required, uniqueIndexElement)
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
      responses:
        '200':
          description: List of metadata queries with category bindings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      example: 123e4567-e89b-12d3-a456-426614174001
                    name:
                      type: string
                      example: Author Name
                    description:
                      type: string
                      nullable: true
                      example: The name of the document author
                    dataType:
                      type: string
                      enum:
                        - STRING
                        - SHORT_STRING
                        - NUMBER
                        - BOOLEAN
                        - DATE
                      example: STRING
                    instructions:
                      type: string
                      example: >-
                        Extract the full name of the primary author from the
                        document header or byline
                    ontologyId:
                      type: string
                      format: uuid
                      example: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                    createdAt:
                      type: string
                      format: date-time
                      example: '2024-01-15T10:30:00Z'
                    updatedAt:
                      type: string
                      nullable: true
                      format: date-time
                      example: '2024-01-15T14:30:00Z'
                    categoryBindings:
                      type: array
                      items:
                        type: object
                        properties:
                          categoryId:
                            type: string
                            format: uuid
                            description: >-
                              The ID of the category this metadata query is
                              bound to
                            example: 123e4567-e89b-12d3-a456-426614174002
                          categoryName:
                            type: string
                            description: >-
                              The name of the category this metadata query is
                              bound to
                            example: Research Papers
                          required:
                            type: boolean
                            description: >-
                              Whether this metadata query is required for this
                              category
                            example: true
                          uniqueIndexElement:
                            type: boolean
                            description: >-
                              Whether this metadata query is part of the unique
                              index for this category
                            example: false
                        required:
                          - categoryId
                          - categoryName
                          - required
                          - uniqueIndexElement
                        description: >-
                          Information about how this metadata query is bound to
                          a specific category
                      description: >-
                        List of categories this metadata query is bound to with
                        binding properties
                  required:
                    - id
                    - name
                    - description
                    - dataType
                    - instructions
                    - ontologyId
                    - createdAt
                    - updatedAt
                    - categoryBindings
                  description: Metadata key with complete category binding information
              example:
                - id: e81bb521-4b01-45ca-a74e-c52c52363181
                  name: Permit Number
                  description: The official permit number assigned by the city
                  dataType: SHORT_STRING
                  instructions: >-
                    Extract the permit number from the document header or
                    official stamp
                  ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                  createdAt: '2025-01-15T10:30:00Z'
                  updatedAt: null
                  categoryBindings:
                    - categoryId: 123e4567-e89b-12d3-a456-426614174000
                      categoryName: Sidewalk Permit
                      required: true
                      uniqueIndexElement: true
                    - categoryId: 456e7890-e89b-12d3-a456-426614174001
                      categoryName: Building Permit
                      required: true
                      uniqueIndexElement: false
                - id: 6bbda475-2aa6-4e36-966c-40f161cce13d
                  name: Inspector Name
                  description: Name of the assigned inspector
                  dataType: STRING
                  instructions: >-
                    Please extract the full name of the inspector from this
                    document.
                  ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                  createdAt: '2025-01-15T10:32:00Z'
                  updatedAt: '2025-01-16T14:20:00Z'
                  categoryBindings:
                    - categoryId: 123e4567-e89b-12d3-a456-426614174000
                      categoryName: Sidewalk Permit
                      required: false
                      uniqueIndexElement: false
        '401':
          description: Unauthorized
        '404':
          description: Ontology not found
  /accounts/{accountId}/ontologies/{ontologyId}/metadata-queries/{metadataQueryId}:
    get:
      operationId: getMetadataQuery
      tags:
        - Metadata Queries
      summary: Get a metadata query by ID
      description: >-
        Returns a single metadata query with its category bindings including
        binding properties (required, uniqueIndexElement)
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the metadata query
          required: true
          description: The ID of the metadata query
          name: metadataQueryId
          in: path
      responses:
        '200':
          description: Metadata key details with category bindings
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 123e4567-e89b-12d3-a456-426614174001
                  name:
                    type: string
                    example: Author Name
                  description:
                    type: string
                    nullable: true
                    example: The name of the document author
                  dataType:
                    type: string
                    enum:
                      - STRING
                      - SHORT_STRING
                      - NUMBER
                      - BOOLEAN
                      - DATE
                    example: STRING
                  instructions:
                    type: string
                    example: >-
                      Extract the full name of the primary author from the
                      document header or byline
                  ontologyId:
                    type: string
                    format: uuid
                    example: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  updatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                  categoryBindings:
                    type: array
                    items:
                      type: object
                      properties:
                        categoryId:
                          type: string
                          format: uuid
                          description: >-
                            The ID of the category this metadata query is bound
                            to
                          example: 123e4567-e89b-12d3-a456-426614174002
                        categoryName:
                          type: string
                          description: >-
                            The name of the category this metadata query is
                            bound to
                          example: Research Papers
                        required:
                          type: boolean
                          description: >-
                            Whether this metadata query is required for this
                            category
                          example: true
                        uniqueIndexElement:
                          type: boolean
                          description: >-
                            Whether this metadata query is part of the unique
                            index for this category
                          example: false
                      required:
                        - categoryId
                        - categoryName
                        - required
                        - uniqueIndexElement
                      description: >-
                        Information about how this metadata query is bound to a
                        specific category
                    description: >-
                      List of categories this metadata query is bound to with
                      binding properties
                required:
                  - id
                  - name
                  - description
                  - dataType
                  - instructions
                  - ontologyId
                  - createdAt
                  - updatedAt
                  - categoryBindings
                description: Metadata key with complete category binding information
              example:
                id: e81bb521-4b01-45ca-a74e-c52c52363181
                name: Permit Number
                description: The official permit number assigned by the city
                dataType: SHORT_STRING
                instructions: >-
                  Extract the permit number from the document header or official
                  stamp
                ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                createdAt: '2025-01-15T10:30:00Z'
                updatedAt: null
                categoryBindings:
                  - categoryId: 123e4567-e89b-12d3-a456-426614174000
                    categoryName: Sidewalk Permit
                    required: true
                    uniqueIndexElement: true
                  - categoryId: 456e7890-e89b-12d3-a456-426614174001
                    categoryName: Building Permit
                    required: true
                    uniqueIndexElement: false
        '401':
          description: Unauthorized
        '404':
          description: Metadata key or ontology not found
    put:
      operationId: updateMetadataQuery
      tags:
        - Metadata Queries
      summary: Update a metadata query
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the metadata query
          required: true
          description: The ID of the metadata query
          name: metadataQueryId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMetadataQuery'
      responses:
        '200':
          description: Metadata key updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataQuery'
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Metadata key or ontology not found
    delete:
      operationId: deleteMetadataQuery
      tags:
        - Metadata Queries
      summary: Delete a metadata query
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the metadata query
          required: true
          description: The ID of the metadata query
          name: metadataQueryId
          in: path
      responses:
        '204':
          description: Metadata key deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Metadata key or ontology not found
  /accounts/{accountId}/ontologies/{ontologyId}/categories/{categoryId}/bindings/{metadataQueryId}:
    put:
      operationId: bindMetadataQueryToCategory
      tags:
        - Metadata Queries
        - Categories
      summary: Bind metadata query to a category
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the category
          required: true
          description: The ID of the category
          name: categoryId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the metadata query
          required: true
          description: The ID of the metadata query
          name: metadataQueryId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindMetadataQuery'
      responses:
        '200':
          description: Metadata key bound to category successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 123e4567-e89b-12d3-a456-426614174001
                  name:
                    type: string
                    example: Research Papers
                  description:
                    type: string
                    nullable: true
                    example: Academic research papers and publications
                  metadataQueryBindings:
                    type: array
                    items:
                      type: string
                      format: uuid
                required:
                  - id
                  - name
                  - description
                  - metadataQueryBindings
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Metadata key, category, or ontology not found
    delete:
      operationId: unbindMetadataQueryFromCategory
      tags:
        - Metadata Queries
        - Categories
      summary: Unbind metadata query from a category
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the category
          required: true
          description: The ID of the category
          name: categoryId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the metadata query
          required: true
          description: The ID of the metadata query
          name: metadataQueryId
          in: path
      responses:
        '204':
          description: Metadata key unbound from category successfully
        '401':
          description: Unauthorized
        '404':
          description: Metadata key, category, or ontology not found
  /accounts/{accountId}/ontologies/{ontologyId}/metadata-queries/{metadataQueryId}/usage-count:
    get:
      operationId: getMetadataQueryUsageCount
      tags:
        - Metadata Queries
      summary: Get metadata query usage count
      description: >-
        Returns the number of categories that currently use this metadata query.

        **Features:** - Efficient counting using SQL COUNT queries with JOIN -
        Returns exact count of categories bound to the metadata query - Useful
        for impact analysis before metadata query changes - Supports ontology
        change management workflows

        **Use Cases:** - Determine impact before deleting a metadata query -
        Analyze metadata query usage across categories - Support ontology change
        management decisions - Dashboard statistics for metadata query
        utilization

        **Example Usage:** - `GET
        /accounts/acc-12345678/ontologies/ont-87654321/metadata-queries/123e4567-e89b-12d3-a456-426614174000/usage-count`

        **Response:** Returns a simple count object indicating how many
        categories are currently bound to this metadata query.

        **Performance:** - Optimized for large ontologies using database indexes
        - Uses SQL COUNT with JOIN for efficient counting - Returns exact counts
        without loading category data into memory
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the metadata query
          required: true
          description: The ID of the metadata query
          name: metadataQueryId
          in: path
      responses:
        '200':
          description: Metadata key usage count retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    minimum: 0
                    description: Number of categories that use this metadata query
                    example: 3
                required:
                  - count
        '401':
          description: Unauthorized
        '404':
          description: Metadata key or ontology not found
  /accounts/{accountId}/ontologies/{ontologyId}/categories:
    post:
      operationId: createCategory
      tags:
        - Categories
      summary: Create a new category
      description: >-
        Creates a new category within an ontology. The new category will
        initially have no bound metadata queries. Use the metadata query binding
        endpoints to associate metadata queries with this category.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCategory'
      responses:
        '201':
          description: Category created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Ontology not found
    get:
      operationId: listCategories
      tags:
        - Categories
      summary: List all categories in an ontology
      description: >-
        Returns all categories with their bound metadata queries. Each metadata
        query includes binding properties that define how the key is used within
        the category (required status and unique index participation).
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
      responses:
        '200':
          description: >-
            List of categories with their bound metadata queries and binding
            properties
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
              example:
                - id: 123e4567-e89b-12d3-a456-426614174000
                  name: Sidewalk Permit
                  description: Permits for sidewalk construction and repair
                  instructions: Ensure proper traffic management during work
                  ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                  boundMetadataQueries:
                    - id: e81bb521-4b01-45ca-a74e-c52c52363181
                      name: Permit Number
                      description: The official permit number assigned by the city
                      instructions: >-
                        Enter the official permit number from the application
                        document
                      dataType: STRING
                      ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                      createdAt: '2025-01-15T10:30:00Z'
                      updatedAt: null
                      binding:
                        required: true
                        uniqueIndexElement: true
                    - id: 372f5d54-f293-4005-8baa-d9555134015f
                      name: Property Address
                      description: Address where the sidewalk work will be performed
                      instructions: >-
                        Provide the complete street address including number,
                        street name, and zip code
                      dataType: STRING
                      ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                      createdAt: '2025-01-15T10:31:00Z'
                      updatedAt: null
                      binding:
                        required: true
                        uniqueIndexElement: false
                    - id: 6bbda475-2aa6-4e36-966c-40f161cce13d
                      name: Inspector Name
                      description: Name of the assigned inspector
                      instructions: >-
                        Enter the full name of the inspector assigned to this
                        permit
                      dataType: STRING
                      ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                      createdAt: '2025-01-15T10:32:00Z'
                      updatedAt: '2025-01-16T14:20:00Z'
                      binding:
                        required: false
                        uniqueIndexElement: false
                  createdAt: '2025-01-15T09:00:00Z'
                  updatedAt: '2025-01-15T15:30:00Z'
        '401':
          description: Unauthorized
        '404':
          description: Ontology not found
  /accounts/{accountId}/ontologies/{ontologyId}/categories/{categoryId}:
    get:
      operationId: getCategory
      tags:
        - Categories
      summary: Get a category by ID
      description: >-
        Returns a single category with its bound metadata queries. Each metadata
        query includes binding properties that specify whether the key is
        required and whether it participates in the unique index for this
        category.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the category
          required: true
          description: The ID of the category
          name: categoryId
          in: path
      responses:
        '200':
          description: >-
            Category details with bound metadata queries and their binding
            properties
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              example:
                id: 123e4567-e89b-12d3-a456-426614174000
                name: Sidewalk Permit
                description: Permits for sidewalk construction and repair
                instructions: Ensure proper traffic management during work
                ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                boundMetadataQueries:
                  - id: e81bb521-4b01-45ca-a74e-c52c52363181
                    name: Permit Number
                    description: The official permit number assigned by the city
                    instructions: >-
                      Enter the official permit number from the application
                      document
                    dataType: STRING
                    ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                    createdAt: '2025-01-15T10:30:00Z'
                    updatedAt: null
                    binding:
                      required: true
                      uniqueIndexElement: true
                  - id: 372f5d54-f293-4005-8baa-d9555134015f
                    name: Property Address
                    description: Address where the sidewalk work will be performed
                    instructions: >-
                      Provide the complete street address including number,
                      street name, and zip code
                    dataType: STRING
                    ontologyId: 987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b
                    createdAt: '2025-01-15T10:31:00Z'
                    updatedAt: null
                    binding:
                      required: true
                      uniqueIndexElement: false
                createdAt: '2025-01-15T09:00:00Z'
                updatedAt: '2025-01-15T15:30:00Z'
        '401':
          description: Unauthorized
        '404':
          description: Category or ontology not found
    put:
      operationId: updateCategory
      tags:
        - Categories
      summary: Update a category
      description: >-
        Updates category properties (name, description, additional
        instructions). This endpoint does not modify metadata query bindings.
        Use the metadata query binding endpoints to manage key associations.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the category
          required: true
          description: The ID of the category
          name: categoryId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCategory'
      responses:
        '200':
          description: Category updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Category or ontology not found
    delete:
      operationId: deleteCategory
      tags:
        - Categories
      summary: Delete a category
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the category
          required: true
          description: The ID of the category
          name: categoryId
          in: path
      responses:
        '204':
          description: Category deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Category or ontology not found
  /accounts/{accountId}/ontologies:
    post:
      operationId: createOntology
      tags:
        - Ontologies
      summary: Create a new ontology
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOntology'
      responses:
        '201':
          description: Ontology created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ontology'
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
    get:
      operationId: listOntologies
      tags:
        - Ontologies
      summary: List all ontologies for an account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '200':
          description: List of ontologies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Ontology'
        '401':
          description: Unauthorized
        '404':
          description: Account not found
  /accounts/{accountId}/ontologies/{ontologyId}:
    get:
      operationId: getOntology
      tags:
        - Ontologies
      summary: Get an ontology by ID
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
      responses:
        '200':
          description: Ontology details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ontology'
        '401':
          description: Unauthorized
        '404':
          description: Ontology not found
    put:
      operationId: updateOntology
      tags:
        - Ontologies
      summary: Update an ontology
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOntology'
      responses:
        '200':
          description: Ontology updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ontology'
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Ontology not found
    delete:
      operationId: deleteOntology
      tags:
        - Ontologies
      summary: Delete an ontology
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
      responses:
        '204':
          description: Ontology deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Ontology not found
  /accounts/{accountId}/ontologies/{ontologyId}/bulk-update:
    post:
      operationId: bulkUpdateOntology
      tags:
        - Ontologies
      summary: Bulk update ontology with multiple operations
      description: >-
        Perform multiple operations on an ontology including updating metadata
        queries, categories, and bindings in a single transaction
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the ontology
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the ontology
          name: ontologyId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accountId:
                  type: string
                  pattern: ^scd-[a-z0-9]{8}$
                  description: Short account ID with scd- prefix
                  example: scd-k2j8n4m1
                ontologyId:
                  type: string
                  format: uuid
                  description: The ID of the ontology
                  example: 123e4567-e89b-12d3-a456-426614174001
                operations:
                  type: object
                  properties:
                    ontology:
                      type: object
                      properties:
                        update:
                          type: object
                          properties:
                            name:
                              type: string
                              minLength: 1
                              example: Updated Research Document Ontology
                            description:
                              type: string
                              nullable: true
                              example: >-
                                Updated description for research document
                                classification
                        delete:
                          type: boolean
                          example: false
                    metadataQueries:
                      type: object
                      properties:
                        create:
                          type: array
                          items:
                            type: object
                            properties:
                              tempId:
                                type: string
                                description: Temporary ID for internal reference
                                example: temp-key-001
                              name:
                                type: string
                                minLength: 1
                                example: Author Name
                              description:
                                type: string
                                nullable: true
                                example: The name of the document author
                              dataType:
                                type: string
                                enum:
                                  - STRING
                                  - SHORT_STRING
                                  - NUMBER
                                  - BOOLEAN
                                  - DATE
                                example: STRING
                              instructions:
                                type: string
                                minLength: 1
                                example: >-
                                  Extract the full name of the primary author
                                  from the document header or byline
                            required:
                              - tempId
                              - name
                              - dataType
                              - instructions
                        update:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174001
                              name:
                                type: string
                                minLength: 1
                                example: Updated Author Name
                              description:
                                type: string
                                nullable: true
                                example: Updated description for author name field
                              dataType:
                                type: string
                                enum:
                                  - STRING
                                  - SHORT_STRING
                                  - NUMBER
                                  - BOOLEAN
                                  - DATE
                                example: STRING
                              instructions:
                                type: string
                                minLength: 1
                                example: >-
                                  Extract the full name of the primary author
                                  from the document header or byline
                            required:
                              - id
                        delete:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174001
                            required:
                              - id
                    categories:
                      type: object
                      properties:
                        create:
                          type: array
                          items:
                            type: object
                            properties:
                              tempId:
                                type: string
                                description: Temporary ID for internal reference
                                example: temp-cat-001
                              name:
                                type: string
                                minLength: 1
                                example: Research Papers
                              description:
                                type: string
                                nullable: true
                                example: Academic research papers and publications
                              instructions:
                                type: string
                                nullable: true
                                example: >-
                                  Please ensure all papers include proper
                                  citations
                              boundMetadataQueries:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      description: Metadata key ID or tempId
                                      example: 123e4567-e89b-12d3-a456-426614174001
                                    binding:
                                      type: object
                                      properties:
                                        required:
                                          type: boolean
                                          example: true
                                        uniqueIndexElement:
                                          type: boolean
                                          example: false
                                      required:
                                        - required
                                        - uniqueIndexElement
                                  required:
                                    - id
                                    - binding
                            required:
                              - tempId
                              - name
                        update:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174001
                              name:
                                type: string
                                minLength: 1
                                example: Updated Research Papers
                              description:
                                type: string
                                nullable: true
                                example: Updated description for research papers
                              instructions:
                                type: string
                                nullable: true
                                example: Updated instructions for paper categorization
                            required:
                              - id
                        delete:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174001
                              success:
                                type: boolean
                                example: true
                              error:
                                type: string
                                example: >-
                                  Cannot delete: category has bound metadata
                                  queries
                            required:
                              - id
                              - success
                    bindings:
                      type: object
                      properties:
                        create:
                          type: array
                          items:
                            type: object
                            properties:
                              categoryId:
                                type: string
                                description: Category ID or tempId
                                example: 123e4567-e89b-12d3-a456-426614174001
                              keyId:
                                type: string
                                description: Metadata key ID or tempId
                                example: 123e4567-e89b-12d3-a456-426614174002
                              binding:
                                type: object
                                properties:
                                  required:
                                    type: boolean
                                    example: true
                                  uniqueIndexElement:
                                    type: boolean
                                    example: false
                                required:
                                  - required
                                  - uniqueIndexElement
                            required:
                              - categoryId
                              - keyId
                              - binding
                        update:
                          type: array
                          items:
                            type: object
                            properties:
                              categoryId:
                                type: string
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174001
                              keyId:
                                type: string
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174002
                              binding:
                                type: object
                                properties:
                                  required:
                                    type: boolean
                                    example: true
                                  uniqueIndexElement:
                                    type: boolean
                                    example: false
                                required:
                                  - required
                                  - uniqueIndexElement
                            required:
                              - categoryId
                              - keyId
                              - binding
                        delete:
                          type: array
                          items:
                            type: object
                            properties:
                              categoryId:
                                type: string
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174001
                              keyId:
                                type: string
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174002
                            required:
                              - categoryId
                              - keyId
              required:
                - accountId
                - ontologyId
                - operations
              description: Bulk update operations for an ontology
      responses:
        '200':
          description: Bulk update completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  results:
                    type: object
                    properties:
                      ontology:
                        type: object
                        properties:
                          updated:
                            type: boolean
                            example: true
                          deleted:
                            type: boolean
                            example: false
                      metadataQueries:
                        type: object
                        properties:
                          created:
                            type: array
                            items:
                              type: object
                              properties:
                                tempId:
                                  type: string
                                  example: temp-key-001
                                id:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174001
                                success:
                                  type: boolean
                                  example: true
                                error:
                                  type: string
                                  example: 'Validation error: name is required'
                              required:
                                - tempId
                                - id
                                - success
                          updated:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174001
                                success:
                                  type: boolean
                                  example: true
                                error:
                                  type: string
                                  example: 'Validation error: name is required'
                              required:
                                - id
                                - success
                          deleted:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174001
                                success:
                                  type: boolean
                                  example: true
                                error:
                                  type: string
                                  example: >-
                                    Cannot delete: key is still bound to
                                    categories
                              required:
                                - id
                                - success
                      categories:
                        type: object
                        properties:
                          created:
                            type: array
                            items:
                              type: object
                              properties:
                                tempId:
                                  type: string
                                  example: temp-cat-001
                                id:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174001
                                success:
                                  type: boolean
                                  example: true
                                error:
                                  type: string
                                  example: 'Validation error: name is required'
                              required:
                                - tempId
                                - id
                                - success
                          updated:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174001
                                success:
                                  type: boolean
                                  example: true
                                error:
                                  type: string
                                  example: 'Validation error: name is required'
                              required:
                                - id
                                - success
                          deleted:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174001
                                success:
                                  type: boolean
                                  example: true
                                error:
                                  type: string
                                  example: >-
                                    Cannot delete: category has bound metadata
                                    queries
                              required:
                                - id
                                - success
                      bindings:
                        type: object
                        properties:
                          created:
                            type: array
                            items:
                              type: object
                              properties:
                                categoryId:
                                  type: string
                                  example: 123e4567-e89b-12d3-a456-426614174001
                                keyId:
                                  type: string
                                  example: 123e4567-e89b-12d3-a456-426614174002
                                success:
                                  type: boolean
                                  example: true
                                error:
                                  type: string
                                  example: Binding already exists
                              required:
                                - categoryId
                                - keyId
                                - success
                          updated:
                            type: array
                            items:
                              type: object
                              properties:
                                categoryId:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174001
                                keyId:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174002
                                success:
                                  type: boolean
                                  example: true
                                error:
                                  type: string
                                  example: Binding not found
                              required:
                                - categoryId
                                - keyId
                                - success
                          deleted:
                            type: array
                            items:
                              type: object
                              properties:
                                categoryId:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174001
                                keyId:
                                  type: string
                                  format: uuid
                                  example: 123e4567-e89b-12d3-a456-426614174002
                                success:
                                  type: boolean
                                  example: true
                                error:
                                  type: string
                                  example: Binding not found
                              required:
                                - categoryId
                                - keyId
                                - success
                  errors:
                    type: array
                    items:
                      type: string
                required:
                  - success
                  - results
                description: Response from bulk ontology update operations
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Ontology not found
  /accounts/{accountId}/workspaces:
    post:
      operationId: createWorkspace
      tags:
        - Workspaces
      summary: Create a new workspace
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspace'
      responses:
        '201':
          description: Workspace created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Account not found
    get:
      operationId: listWorkspaces
      tags:
        - Workspaces
      summary: List all workspaces for an account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '200':
          description: List of workspaces
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Workspace'
        '401':
          description: Unauthorized
        '404':
          description: Account not found
  /accounts/{accountId}/workspaces/{workspaceId}:
    get:
      operationId: getWorkspace
      tags:
        - Workspaces
      summary: Get a workspace by ID
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            pattern: ^sws-[a-z0-9]{8}$
            description: Short workspace ID with sws- prefix
            example: sws-x9p3q7r5
          required: true
          description: Short workspace ID with sws- prefix
          name: workspaceId
          in: path
      responses:
        '200':
          description: Workspace details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          description: Unauthorized
        '404':
          description: Workspace not found
    put:
      operationId: updateWorkspace
      tags:
        - Workspaces
      summary: Update a workspace
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            pattern: ^sws-[a-z0-9]{8}$
            description: Short workspace ID with sws- prefix
            example: sws-x9p3q7r5
          required: true
          description: Short workspace ID with sws- prefix
          name: workspaceId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspace'
      responses:
        '200':
          description: Workspace updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Workspace not found
    delete:
      operationId: deleteWorkspace
      tags:
        - Workspaces
      summary: Delete a workspace
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            pattern: ^sws-[a-z0-9]{8}$
            description: Short workspace ID with sws- prefix
            example: sws-x9p3q7r5
          required: true
          description: Short workspace ID with sws- prefix
          name: workspaceId
          in: path
      responses:
        '204':
          description: Workspace deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Workspace not found
  /accounts/{accountId}/libraries:
    post:
      operationId: createLibrary
      tags:
        - Libraries
      summary: Create a new library
      description: >-
        Creates a new library within an account. Libraries can be bound to
        workspaces to provide access to external resources via their root URL.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Name of the library
                  example: Research Library
                rootUrl:
                  type: string
                  format: uri
                  description: Root URL of the library
                  example: https://library.example.com
                urlFilter:
                  type: string
                  description: >-
                    Regular expression to filter URLs when building the library.
                    If not provided, uses rootUrl as prefix
                  example: https://library\.example\.com/docs/.*
              required:
                - name
                - rootUrl
              description: Data for creating a new library
      responses:
        '201':
          description: Library created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 123e4567-e89b-12d3-a456-426614174001
                  name:
                    type: string
                    example: Research Library
                  rootUrl:
                    type: string
                    format: uri
                    example: https://library.example.com
                  urlFilter:
                    type: string
                    nullable: true
                    description: >-
                      Regular expression to filter URLs when building the
                      library. If not provided, uses rootUrl as prefix
                    example: https://library\.example\.com/docs/.*
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    example: scd-k2j8n4m1
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  updatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - id
                  - name
                  - rootUrl
                  - accountId
                  - createdAt
                  - updatedAt
                description: Representation of a library
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
    get:
      operationId: listLibraries
      tags:
        - Libraries
      summary: List all libraries in an account
      description: Returns all libraries owned by the account.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '200':
          description: List of libraries
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      example: 123e4567-e89b-12d3-a456-426614174001
                    name:
                      type: string
                      example: Research Library
                    rootUrl:
                      type: string
                      format: uri
                      example: https://library.example.com
                    urlFilter:
                      type: string
                      nullable: true
                      description: >-
                        Regular expression to filter URLs when building the
                        library. If not provided, uses rootUrl as prefix
                      example: https://library\.example\.com/docs/.*
                    accountId:
                      type: string
                      pattern: ^scd-[a-z0-9]{8}$
                      example: scd-k2j8n4m1
                    createdAt:
                      type: string
                      format: date-time
                      example: '2024-01-15T10:30:00Z'
                    updatedAt:
                      type: string
                      nullable: true
                      format: date-time
                      example: '2024-01-15T14:30:00Z'
                  required:
                    - id
                    - name
                    - rootUrl
                    - accountId
                    - createdAt
                    - updatedAt
                  description: Representation of a library
              example:
                - id: 123e4567-e89b-12d3-a456-426614174001
                  name: Research Library
                  rootUrl: https://library.example.com
                  accountId: scd-k2j8n4m1
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: null
                - id: 456e7890-e12b-34d5-b678-901234567890
                  name: Reference Materials
                  rootUrl: https://refs.example.org
                  accountId: scd-k2j8n4m1
                  createdAt: '2024-01-16T14:20:00Z'
                  updatedAt: '2024-01-17T09:15:00Z'
        '401':
          description: Unauthorized
  /accounts/{accountId}/libraries/{libraryId}:
    get:
      operationId: getLibrary
      tags:
        - Libraries
      summary: Get a library by ID
      description: Returns a single library with its details.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the library
          required: true
          description: The ID of the library
          name: libraryId
          in: path
      responses:
        '200':
          description: Library details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 123e4567-e89b-12d3-a456-426614174001
                  name:
                    type: string
                    example: Research Library
                  rootUrl:
                    type: string
                    format: uri
                    example: https://library.example.com
                  urlFilter:
                    type: string
                    nullable: true
                    description: >-
                      Regular expression to filter URLs when building the
                      library. If not provided, uses rootUrl as prefix
                    example: https://library\.example\.com/docs/.*
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    example: scd-k2j8n4m1
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  updatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - id
                  - name
                  - rootUrl
                  - accountId
                  - createdAt
                  - updatedAt
                description: Representation of a library
              example:
                id: 123e4567-e89b-12d3-a456-426614174001
                name: Research Library
                rootUrl: https://library.example.com
                accountId: scd-k2j8n4m1
                createdAt: '2024-01-15T10:30:00Z'
                updatedAt: null
        '401':
          description: Unauthorized
        '404':
          description: Library not found
    put:
      operationId: updateLibrary
      tags:
        - Libraries
      summary: Update a library
      description: >-
        Updates library properties (name, root URL). This endpoint does not
        modify workspace bindings.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the library
          required: true
          description: The ID of the library
          name: libraryId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Name of the library
                  example: Updated Research Library
                rootUrl:
                  type: string
                  format: uri
                  description: Root URL of the library
                  example: https://updated-library.example.com
                urlFilter:
                  type: string
                  nullable: true
                  description: >-
                    Regular expression to filter URLs when building the library.
                    If not provided, uses rootUrl as prefix
                  example: https://updated-library\.example\.com/docs/.*
              description: Data for updating a library
      responses:
        '200':
          description: Library updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 123e4567-e89b-12d3-a456-426614174001
                  name:
                    type: string
                    example: Research Library
                  rootUrl:
                    type: string
                    format: uri
                    example: https://library.example.com
                  urlFilter:
                    type: string
                    nullable: true
                    description: >-
                      Regular expression to filter URLs when building the
                      library. If not provided, uses rootUrl as prefix
                    example: https://library\.example\.com/docs/.*
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    example: scd-k2j8n4m1
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  updatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - id
                  - name
                  - rootUrl
                  - accountId
                  - createdAt
                  - updatedAt
                description: Representation of a library
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Library not found
    delete:
      operationId: deleteLibrary
      tags:
        - Libraries
      summary: Delete a library
      description: >-
        Deletes a library and all its workspace bindings. This action cannot be
        undone.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the library
          required: true
          description: The ID of the library
          name: libraryId
          in: path
      responses:
        '204':
          description: Library deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Library not found
  /accounts/{accountId}/workspaces/{workspaceId}/libraries:
    post:
      operationId: bindLibraryToWorkspace
      tags:
        - Library Bindings
      summary: Bind a library to a workspace
      description: >-
        Creates a binding between a library and a workspace, allowing the
        workspace to access the library's resources.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            pattern: ^sws-[a-z0-9]{8}$
            description: Short workspace ID with sws- prefix
            example: sws-x9p3q7r5
          required: true
          description: Short workspace ID with sws- prefix
          name: workspaceId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                libraryId:
                  type: string
                  format: uuid
                  description: The ID of the library to bind to the workspace
                  example: 123e4567-e89b-12d3-a456-426614174001
              required:
                - libraryId
              description: Data for binding a library to a workspace
      responses:
        '201':
          description: Library bound to workspace successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  libraryId:
                    type: string
                    format: uuid
                    example: 123e4567-e89b-12d3-a456-426614174001
                  workspaceId:
                    type: string
                    example: sws-x9p3q7r5
                  createdAt:
                    type: string
                    example: '2024-01-15T11:00:00Z'
                required:
                  - libraryId
                  - workspaceId
                  - createdAt
              example:
                libraryId: 123e4567-e89b-12d3-a456-426614174001
                workspaceId: sws-x9p3q7r5
                createdAt: '2024-01-15T11:00:00Z'
        '400':
          description: Invalid input data or library already bound to workspace
        '401':
          description: Unauthorized
        '404':
          description: Library or workspace not found
    get:
      operationId: listWorkspaceLibraries
      tags:
        - Library Bindings
      summary: List libraries bound to a workspace
      description: >-
        Returns all libraries bound to the specified workspace with their
        binding information.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            pattern: ^sws-[a-z0-9]{8}$
            description: Short workspace ID with sws- prefix
            example: sws-x9p3q7r5
          required: true
          description: Short workspace ID with sws- prefix
          name: workspaceId
          in: path
      responses:
        '200':
          description: List of libraries bound to the workspace
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      example: 123e4567-e89b-12d3-a456-426614174001
                    name:
                      type: string
                      example: Research Library
                    rootUrl:
                      type: string
                      format: uri
                      example: https://library.example.com
                    urlFilter:
                      type: string
                      nullable: true
                      description: >-
                        Regular expression to filter URLs when building the
                        library. If not provided, uses rootUrl as prefix
                      example: https://library\.example\.com/docs/.*
                    accountId:
                      type: string
                      pattern: ^scd-[a-z0-9]{8}$
                      example: scd-k2j8n4m1
                    createdAt:
                      type: string
                      format: date-time
                      example: '2024-01-15T10:30:00Z'
                    updatedAt:
                      type: string
                      nullable: true
                      format: date-time
                      example: '2024-01-15T14:30:00Z'
                    binding:
                      type: object
                      properties:
                        createdAt:
                          type: string
                          format: date-time
                          description: When this library was bound to the workspace
                          example: '2024-01-15T10:30:00Z'
                      required:
                        - createdAt
                      description: Binding properties for this library in this workspace
                  required:
                    - id
                    - name
                    - rootUrl
                    - accountId
                    - createdAt
                    - updatedAt
                    - binding
                  description: Library with its binding properties for a workspace
              example:
                - id: 123e4567-e89b-12d3-a456-426614174001
                  name: Research Library
                  rootUrl: https://library.example.com
                  accountId: scd-k2j8n4m1
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: null
                  binding:
                    createdAt: '2024-01-15T11:00:00Z'
                - id: 456e7890-e12b-34d5-b678-901234567890
                  name: Reference Materials
                  rootUrl: https://refs.example.org
                  accountId: scd-k2j8n4m1
                  createdAt: '2024-01-16T14:20:00Z'
                  updatedAt: '2024-01-17T09:15:00Z'
                  binding:
                    createdAt: '2024-01-16T15:30:00Z'
        '401':
          description: Unauthorized
        '404':
          description: Workspace not found
  /accounts/{accountId}/workspaces/{workspaceId}/libraries/{libraryId}:
    delete:
      operationId: removeLibraryFromWorkspace
      tags:
        - Library Bindings
      summary: Remove a library binding from a workspace
      description: >-
        Removes the binding between a library and a workspace. The library
        itself is not deleted.
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            pattern: ^sws-[a-z0-9]{8}$
            description: Short workspace ID with sws- prefix
            example: sws-x9p3q7r5
          required: true
          description: Short workspace ID with sws- prefix
          name: workspaceId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the library
          required: true
          description: The ID of the library
          name: libraryId
          in: path
      responses:
        '204':
          description: Library binding removed successfully
        '401':
          description: Unauthorized
        '404':
          description: Library, workspace, or binding not found
  /accounts:
    post:
      operationId: createAccount
      tags:
        - Accounts
      summary: Create a new account
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccount'
      responses:
        '201':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Invalid input data
    get:
      operationId: listAccounts
      tags:
        - Accounts
      summary: List all accounts
      parameters:
        - schema:
            type: string
            format: email
            description: Filter accounts by user email
          required: false
          description: Filter accounts by user email
          name: userEmail
          in: query
      responses:
        '200':
          description: List of accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized
  /accounts/{accountId}:
    get:
      operationId: getAccount
      tags:
        - Accounts
      summary: Get an account by ID
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized
        '404':
          description: Account not found
    put:
      operationId: updateAccount
      tags:
        - Accounts
      summary: Update an account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAccount'
      responses:
        '200':
          description: Account updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Invalid input data
        '401':
          description: Unauthorized
        '404':
          description: Account not found
    delete:
      operationId: deleteAccount
      tags:
        - Accounts
      summary: Delete an account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '204':
          description: Account deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Account not found
  /accounts/{accountId}/users:
    post:
      operationId: createUser
      tags:
        - Users
      summary: Create a new user for an account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid request body
        '404':
          description: Account not found
    get:
      operationId: listUsers
      tags:
        - Users
      summary: List all users for an account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '404':
          description: Account not found
  /accounts/{accountId}/users/{userId}:
    get:
      operationId: getUser
      tags:
        - Users
      summary: Get a specific user by ID
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the user
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the user
          name: userId
          in: path
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User or account not found
    put:
      operationId: updateUser
      tags:
        - Users
      summary: Update a user
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the user
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the user
          name: userId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid request body
        '404':
          description: User or account not found
    delete:
      operationId: deleteUser
      tags:
        - Users
      summary: Delete a user
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The ID of the user
            example: 123e4567-e89b-12d3-a456-426614174001
          required: true
          description: The ID of the user
          name: userId
          in: path
      responses:
        '204':
          description: User deleted successfully
        '404':
          description: User or account not found
  /accounts/{accountId}/agents:
    post:
      operationId: createAgent
      tags:
        - Agents
      summary: Create a new AI agent for an account
      description: >-
        Creates a new AI agent with specified instructions and behavior for the
        account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Name of the agent
                  example: Document Categorization Agent
                description:
                  type: string
                  minLength: 1
                  description: Description of the agent's purpose
                  example: >-
                    Categorizes incoming documents according to the dataspace
                    ontology
                instructions:
                  type: string
                  minLength: 1
                  description: >-
                    Text instructions that act as a system prompt describing the
                    agent's general behavior across all tasks
                  example: >-
                    You are a document categorization agent. Analyze incoming
                    documents and categorize them according to the provided
                    ontology. Always provide clear reasoning for your
                    categorization decisions.
                defaultContext:
                  type: object
                  nullable: true
                  properties:
                    libraries:
                      type: array
                      items:
                        type: string
                        format: uuid
                      description: Array of library IDs to include in search context
                      example:
                        - 01234567-89ab-cdef-0123-456789abcdef
                    includeWebSearchResults:
                      type: boolean
                      default: false
                      description: >-
                        Whether to include web search results in addition to
                        local document search. Default is false.
                      example: false
                  additionalProperties: false
                  description: >-
                    Optional default context configuration that will be
                    pre-selected when using this agent
              required:
                - name
                - description
                - instructions
              description: Data for creating a new agent
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  agentId:
                    type: string
                    format: uuid
                    description: The UUID of the agent
                    example: 550e8400-e29b-41d4-a716-446655440000
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    description: Short account ID with scd- prefix
                    example: scd-k2j8n4m1
                  name:
                    type: string
                    description: Name of the agent
                    example: Document Categorization Agent
                  description:
                    type: string
                    description: Description of the agent's purpose
                    example: >-
                      Categorizes incoming documents according to the dataspace
                      ontology
                  instructions:
                    type: string
                    description: >-
                      Text instructions that act as a system prompt describing
                      the agent's general behavior across all tasks
                    example: >-
                      You are a document categorization agent. Analyze incoming
                      documents and categorize them according to the provided
                      ontology.
                  defaultContext:
                    type: object
                    nullable: true
                    properties:
                      libraries:
                        type: array
                        items:
                          type: string
                          format: uuid
                        description: Array of library IDs to include in search context
                        example:
                          - 01234567-89ab-cdef-0123-456789abcdef
                      includeWebSearchResults:
                        type: boolean
                        default: false
                        description: >-
                          Whether to include web search results in addition to
                          local document search. Default is false.
                        example: false
                    additionalProperties: false
                    description: >-
                      Optional default context configuration that will be
                      pre-selected when using this agent
                  createdBy:
                    type: string
                    format: uuid
                    description: ID of the user that created the agent
                    example: 123e4567-e89b-12d3-a456-426614174001
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  lastUpdatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - agentId
                  - accountId
                  - name
                  - description
                  - instructions
                  - createdBy
                  - createdAt
                  - lastUpdatedAt
                description: An AI agent in the system
        '400':
          description: Invalid request body
        '404':
          description: Account not found
    get:
      operationId: listAgents
      tags:
        - Agents
      summary: List all agents for an account
      description: Retrieves a list of all AI agents associated with the specified account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '200':
          description: List of agents retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    agentId:
                      type: string
                      format: uuid
                      description: The UUID of the agent
                      example: 550e8400-e29b-41d4-a716-446655440000
                    accountId:
                      type: string
                      pattern: ^scd-[a-z0-9]{8}$
                      description: Short account ID with scd- prefix
                      example: scd-k2j8n4m1
                    name:
                      type: string
                      description: Name of the agent
                      example: Document Categorization Agent
                    description:
                      type: string
                      description: Description of the agent's purpose
                      example: >-
                        Categorizes incoming documents according to the
                        dataspace ontology
                    instructions:
                      type: string
                      description: >-
                        Text instructions that act as a system prompt describing
                        the agent's general behavior across all tasks
                      example: >-
                        You are a document categorization agent. Analyze
                        incoming documents and categorize them according to the
                        provided ontology.
                    defaultContext:
                      type: object
                      nullable: true
                      properties:
                        libraries:
                          type: array
                          items:
                            type: string
                            format: uuid
                          description: Array of library IDs to include in search context
                          example:
                            - 01234567-89ab-cdef-0123-456789abcdef
                        includeWebSearchResults:
                          type: boolean
                          default: false
                          description: >-
                            Whether to include web search results in addition to
                            local document search. Default is false.
                          example: false
                      additionalProperties: false
                      description: >-
                        Optional default context configuration that will be
                        pre-selected when using this agent
                    createdBy:
                      type: string
                      format: uuid
                      description: ID of the user that created the agent
                      example: 123e4567-e89b-12d3-a456-426614174001
                    createdAt:
                      type: string
                      format: date-time
                      example: '2024-01-15T10:30:00Z'
                    lastUpdatedAt:
                      type: string
                      nullable: true
                      format: date-time
                      example: '2024-01-15T14:30:00Z'
                  required:
                    - agentId
                    - accountId
                    - name
                    - description
                    - instructions
                    - createdBy
                    - createdAt
                    - lastUpdatedAt
                  description: An AI agent in the system
        '404':
          description: Account not found
  /accounts/{accountId}/agents/{agentId}:
    get:
      operationId: getAgent
      tags:
        - Agents
      summary: Get a specific agent by ID
      description: Retrieves detailed information about a specific AI agent
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The UUID of the agent
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          description: The UUID of the agent
          name: agentId
          in: path
      responses:
        '200':
          description: Agent retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  agentId:
                    type: string
                    format: uuid
                    description: The UUID of the agent
                    example: 550e8400-e29b-41d4-a716-446655440000
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    description: Short account ID with scd- prefix
                    example: scd-k2j8n4m1
                  name:
                    type: string
                    description: Name of the agent
                    example: Document Categorization Agent
                  description:
                    type: string
                    description: Description of the agent's purpose
                    example: >-
                      Categorizes incoming documents according to the dataspace
                      ontology
                  instructions:
                    type: string
                    description: >-
                      Text instructions that act as a system prompt describing
                      the agent's general behavior across all tasks
                    example: >-
                      You are a document categorization agent. Analyze incoming
                      documents and categorize them according to the provided
                      ontology.
                  defaultContext:
                    type: object
                    nullable: true
                    properties:
                      libraries:
                        type: array
                        items:
                          type: string
                          format: uuid
                        description: Array of library IDs to include in search context
                        example:
                          - 01234567-89ab-cdef-0123-456789abcdef
                      includeWebSearchResults:
                        type: boolean
                        default: false
                        description: >-
                          Whether to include web search results in addition to
                          local document search. Default is false.
                        example: false
                    additionalProperties: false
                    description: >-
                      Optional default context configuration that will be
                      pre-selected when using this agent
                  createdBy:
                    type: string
                    format: uuid
                    description: ID of the user that created the agent
                    example: 123e4567-e89b-12d3-a456-426614174001
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  lastUpdatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - agentId
                  - accountId
                  - name
                  - description
                  - instructions
                  - createdBy
                  - createdAt
                  - lastUpdatedAt
                description: An AI agent in the system
        '404':
          description: Agent not found
    put:
      operationId: updateAgent
      tags:
        - Agents
      summary: Update an existing agent
      description: Updates the properties of an existing AI agent
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The UUID of the agent
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          description: The UUID of the agent
          name: agentId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Name of the agent
                  example: Updated Document Categorization Agent
                description:
                  type: string
                  minLength: 1
                  description: Description of the agent's purpose
                  example: Updated description for document categorization
                instructions:
                  type: string
                  minLength: 1
                  description: >-
                    Text instructions that act as a system prompt describing the
                    agent's general behavior across all tasks
                  example: Updated instructions for document categorization behavior
                defaultContext:
                  type: object
                  nullable: true
                  properties:
                    libraries:
                      type: array
                      items:
                        type: string
                        format: uuid
                      description: Array of library IDs to include in search context
                      example:
                        - 01234567-89ab-cdef-0123-456789abcdef
                    includeWebSearchResults:
                      type: boolean
                      default: false
                      description: >-
                        Whether to include web search results in addition to
                        local document search. Default is false.
                      example: false
                  additionalProperties: false
                  description: >-
                    Optional default context configuration that will be
                    pre-selected when using this agent
              description: Data for updating an agent
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  agentId:
                    type: string
                    format: uuid
                    description: The UUID of the agent
                    example: 550e8400-e29b-41d4-a716-446655440000
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    description: Short account ID with scd- prefix
                    example: scd-k2j8n4m1
                  name:
                    type: string
                    description: Name of the agent
                    example: Document Categorization Agent
                  description:
                    type: string
                    description: Description of the agent's purpose
                    example: >-
                      Categorizes incoming documents according to the dataspace
                      ontology
                  instructions:
                    type: string
                    description: >-
                      Text instructions that act as a system prompt describing
                      the agent's general behavior across all tasks
                    example: >-
                      You are a document categorization agent. Analyze incoming
                      documents and categorize them according to the provided
                      ontology.
                  defaultContext:
                    type: object
                    nullable: true
                    properties:
                      libraries:
                        type: array
                        items:
                          type: string
                          format: uuid
                        description: Array of library IDs to include in search context
                        example:
                          - 01234567-89ab-cdef-0123-456789abcdef
                      includeWebSearchResults:
                        type: boolean
                        default: false
                        description: >-
                          Whether to include web search results in addition to
                          local document search. Default is false.
                        example: false
                    additionalProperties: false
                    description: >-
                      Optional default context configuration that will be
                      pre-selected when using this agent
                  createdBy:
                    type: string
                    format: uuid
                    description: ID of the user that created the agent
                    example: 123e4567-e89b-12d3-a456-426614174001
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  lastUpdatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - agentId
                  - accountId
                  - name
                  - description
                  - instructions
                  - createdBy
                  - createdAt
                  - lastUpdatedAt
                description: An AI agent in the system
        '400':
          description: Invalid request body
        '404':
          description: Agent not found
    delete:
      operationId: deleteAgent
      tags:
        - Agents
      summary: Delete an agent
      description: Permanently deletes an AI agent from the account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The UUID of the agent
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          description: The UUID of the agent
          name: agentId
          in: path
      responses:
        '204':
          description: Agent deleted successfully
        '404':
          description: Agent not found
  /accounts/{accountId}/task-definitions:
    post:
      operationId: createTaskDefinition
      tags:
        - Task Definitions
      summary: Create a new task definition for an account
      description: >-
        Creates a new task definition with specified model, and instructions for
        the task
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                modelId:
                  type: string
                  enum:
                    - claude-4-sonnet
                    - gpt-4.1
                    - llama-4-maverick
                  description: AI model to use for task execution
                  example: claude-4-sonnet
                name:
                  type: string
                  minLength: 1
                  description: Name of the task definition
                  example: Categorize Document
                taskInstructions:
                  type: string
                  minLength: 1
                  description: Instructions for executing the task
                  example: >-
                    We have received the following document. Please select its
                    best appropriate category from the options in the ontology
                primaryScope:
                  type: string
                  enum:
                    - content
                    - query
                    - dataspace
                  description: >-
                    The type of object that will act as primary context for the
                    task execution
                  example: content
                persistOutput:
                  type: boolean
                  description: Whether to persist the output of the task in the dataspace
                  example: true
                persistLogs:
                  type: boolean
                  description: >-
                    Whether to persist logs of the task execution in the
                    dataspace
                  example: false
              required:
                - modelId
                - name
                - taskInstructions
                - primaryScope
                - persistOutput
                - persistLogs
              description: Data for creating a new task definition
      responses:
        '201':
          description: Task definition created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskDefinitionId:
                    type: string
                    format: uuid
                    description: The UUID of the task definition
                    example: 550e8400-e29b-41d4-a716-446655440000
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    description: Short account ID with scd- prefix
                    example: scd-k2j8n4m1
                  modelId:
                    type: string
                    enum:
                      - claude-4-sonnet
                      - gpt-4.1
                      - llama-4-maverick
                    description: AI model to use for task execution
                    example: claude-4-sonnet
                  name:
                    type: string
                    description: Name of the task definition
                    example: Categorize Document
                  taskInstructions:
                    type: string
                    description: Instructions for executing the task
                    example: >-
                      We have received the following document. Please select its
                      best appropriate category from the options in the ontology
                  primaryScope:
                    type: string
                    enum:
                      - content
                      - query
                      - dataspace
                    description: >-
                      The type of object that will act as primary context for
                      the task execution
                    example: content
                  persistOutput:
                    type: boolean
                    description: Whether to persist the output of the task in the dataspace
                    example: true
                  persistLogs:
                    type: boolean
                    description: >-
                      Whether to persist logs of the task execution in the
                      dataspace
                    example: false
                  taskNameSlug:
                    type: string
                    description: URL-friendly version of the task name
                    example: categorize-document
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  lastUpdatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - taskDefinitionId
                  - accountId
                  - modelId
                  - name
                  - taskInstructions
                  - primaryScope
                  - persistOutput
                  - persistLogs
                  - taskNameSlug
                  - createdAt
                  - lastUpdatedAt
                description: A task definition in the system
        '400':
          description: Invalid request body
        '404':
          description: Account not found
    get:
      operationId: listTaskDefinitions
      tags:
        - Task Definitions
      summary: List all task definitions for an account
      description: >-
        Retrieves a list of all task definitions associated with the specified
        account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '200':
          description: List of task definitions retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    taskDefinitionId:
                      type: string
                      format: uuid
                      description: The UUID of the task definition
                      example: 550e8400-e29b-41d4-a716-446655440000
                    accountId:
                      type: string
                      pattern: ^scd-[a-z0-9]{8}$
                      description: Short account ID with scd- prefix
                      example: scd-k2j8n4m1
                    modelId:
                      type: string
                      enum:
                        - claude-4-sonnet
                        - gpt-4.1
                        - llama-4-maverick
                      description: AI model to use for task execution
                      example: claude-4-sonnet
                    name:
                      type: string
                      description: Name of the task definition
                      example: Categorize Document
                    taskInstructions:
                      type: string
                      description: Instructions for executing the task
                      example: >-
                        We have received the following document. Please select
                        its best appropriate category from the options in the
                        ontology
                    primaryScope:
                      type: string
                      enum:
                        - content
                        - query
                        - dataspace
                      description: >-
                        The type of object that will act as primary context for
                        the task execution
                      example: content
                    persistOutput:
                      type: boolean
                      description: >-
                        Whether to persist the output of the task in the
                        dataspace
                      example: true
                    persistLogs:
                      type: boolean
                      description: >-
                        Whether to persist logs of the task execution in the
                        dataspace
                      example: false
                    taskNameSlug:
                      type: string
                      description: URL-friendly version of the task name
                      example: categorize-document
                    createdAt:
                      type: string
                      format: date-time
                      example: '2024-01-15T10:30:00Z'
                    lastUpdatedAt:
                      type: string
                      nullable: true
                      format: date-time
                      example: '2024-01-15T14:30:00Z'
                  required:
                    - taskDefinitionId
                    - accountId
                    - modelId
                    - name
                    - taskInstructions
                    - primaryScope
                    - persistOutput
                    - persistLogs
                    - taskNameSlug
                    - createdAt
                    - lastUpdatedAt
                  description: A task definition in the system
        '404':
          description: Account not found
  /accounts/{accountId}/task-definitions/{taskDefinitionId}:
    get:
      operationId: getTaskDefinition
      tags:
        - Task Definitions
      summary: Get a specific task definition by ID
      description: Retrieves detailed information about a specific task definition
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The UUID of the task definition
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          description: The UUID of the task definition
          name: taskDefinitionId
          in: path
      responses:
        '200':
          description: Task definition retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskDefinitionId:
                    type: string
                    format: uuid
                    description: The UUID of the task definition
                    example: 550e8400-e29b-41d4-a716-446655440000
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    description: Short account ID with scd- prefix
                    example: scd-k2j8n4m1
                  modelId:
                    type: string
                    enum:
                      - claude-4-sonnet
                      - gpt-4.1
                      - llama-4-maverick
                    description: AI model to use for task execution
                    example: claude-4-sonnet
                  name:
                    type: string
                    description: Name of the task definition
                    example: Categorize Document
                  taskInstructions:
                    type: string
                    description: Instructions for executing the task
                    example: >-
                      We have received the following document. Please select its
                      best appropriate category from the options in the ontology
                  primaryScope:
                    type: string
                    enum:
                      - content
                      - query
                      - dataspace
                    description: >-
                      The type of object that will act as primary context for
                      the task execution
                    example: content
                  persistOutput:
                    type: boolean
                    description: Whether to persist the output of the task in the dataspace
                    example: true
                  persistLogs:
                    type: boolean
                    description: >-
                      Whether to persist logs of the task execution in the
                      dataspace
                    example: false
                  taskNameSlug:
                    type: string
                    description: URL-friendly version of the task name
                    example: categorize-document
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  lastUpdatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - taskDefinitionId
                  - accountId
                  - modelId
                  - name
                  - taskInstructions
                  - primaryScope
                  - persistOutput
                  - persistLogs
                  - taskNameSlug
                  - createdAt
                  - lastUpdatedAt
                description: A task definition in the system
        '404':
          description: Task definition not found
    put:
      operationId: updateTaskDefinition
      tags:
        - Task Definitions
      summary: Update an existing task definition
      description: Updates the properties of an existing task definition
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The UUID of the task definition
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          description: The UUID of the task definition
          name: taskDefinitionId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                modelId:
                  type: string
                  enum:
                    - claude-4-sonnet
                    - gpt-4.1
                    - llama-4-maverick
                  description: AI model to use for task execution
                  example: gpt-4.1
                name:
                  type: string
                  minLength: 1
                  description: Name of the task definition
                  example: Updated Categorize Document
                taskInstructions:
                  type: string
                  minLength: 1
                  description: Instructions for executing the task
                  example: Updated instructions for document categorization
                primaryScope:
                  type: string
                  enum:
                    - content
                    - query
                    - dataspace
                  description: >-
                    The type of object that will act as primary context for the
                    task execution
                  example: query
                persistOutput:
                  type: boolean
                  description: Whether to persist the output of the task in the dataspace
                  example: false
                persistLogs:
                  type: boolean
                  description: >-
                    Whether to persist logs of the task execution in the
                    dataspace
                  example: true
              description: Data for updating a task definition
      responses:
        '200':
          description: Task definition updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskDefinitionId:
                    type: string
                    format: uuid
                    description: The UUID of the task definition
                    example: 550e8400-e29b-41d4-a716-446655440000
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    description: Short account ID with scd- prefix
                    example: scd-k2j8n4m1
                  modelId:
                    type: string
                    enum:
                      - claude-4-sonnet
                      - gpt-4.1
                      - llama-4-maverick
                    description: AI model to use for task execution
                    example: claude-4-sonnet
                  name:
                    type: string
                    description: Name of the task definition
                    example: Categorize Document
                  taskInstructions:
                    type: string
                    description: Instructions for executing the task
                    example: >-
                      We have received the following document. Please select its
                      best appropriate category from the options in the ontology
                  primaryScope:
                    type: string
                    enum:
                      - content
                      - query
                      - dataspace
                    description: >-
                      The type of object that will act as primary context for
                      the task execution
                    example: content
                  persistOutput:
                    type: boolean
                    description: Whether to persist the output of the task in the dataspace
                    example: true
                  persistLogs:
                    type: boolean
                    description: >-
                      Whether to persist logs of the task execution in the
                      dataspace
                    example: false
                  taskNameSlug:
                    type: string
                    description: URL-friendly version of the task name
                    example: categorize-document
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  lastUpdatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - taskDefinitionId
                  - accountId
                  - modelId
                  - name
                  - taskInstructions
                  - primaryScope
                  - persistOutput
                  - persistLogs
                  - taskNameSlug
                  - createdAt
                  - lastUpdatedAt
                description: A task definition in the system
        '400':
          description: Invalid request body
        '404':
          description: Task definition not found
    delete:
      operationId: deleteTaskDefinition
      tags:
        - Task Definitions
      summary: Delete a task definition
      description: Permanently deletes a task definition from the account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The UUID of the task definition
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          description: The UUID of the task definition
          name: taskDefinitionId
          in: path
      responses:
        '204':
          description: Task definition deleted successfully
        '404':
          description: Task definition not found
  /accounts/{accountId}/workflows:
    post:
      operationId: createWorkflow
      tags:
        - Workflows
      summary: Create a new workflow for an account
      description: >-
        Creates a new workflow with specified name, description, and task DAG
        for the account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Name of the workflow
                  example: Document Processing Pipeline
                description:
                  type: string
                  minLength: 1
                  description: Description of the workflow
                  example: >-
                    A workflow that processes incoming documents through
                    categorization and metadata extraction
                taskDag:
                  type: object
                  additionalProperties:
                    type: array
                    items:
                      type: string
                      format: uuid
                    description: Array of task IDs this task depends on
                  description: >-
                    Task dependency graph represented as an adjacency list,
                    where every key is a taskId and the value is an array of
                    taskIds that must be completed before the key can be run
                  example:
                    550e8400-e29b-41d4-a716-446655440001: []
                    550e8400-e29b-41d4-a716-446655440002:
                      - 550e8400-e29b-41d4-a716-446655440001
                    550e8400-e29b-41d4-a716-446655440003:
                      - 550e8400-e29b-41d4-a716-446655440001
                    550e8400-e29b-41d4-a716-446655440004:
                      - 550e8400-e29b-41d4-a716-446655440002
                      - 550e8400-e29b-41d4-a716-446655440003
              required:
                - name
                - description
                - taskDag
              description: Data for creating a new workflow
      responses:
        '201':
          description: Workflow created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The UUID of the workflow
                    example: 550e8400-e29b-41d4-a716-446655440000
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    description: Short account ID with scd- prefix
                    example: scd-k2j8n4m1
                  name:
                    type: string
                    description: Name of the workflow
                    example: Document Processing Pipeline
                  description:
                    type: string
                    description: Description of the workflow
                    example: >-
                      A workflow that processes incoming documents through
                      categorization and metadata extraction
                  taskDag:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                        format: uuid
                      description: Array of task IDs this task depends on
                    description: >-
                      Task dependency graph represented as an adjacency list,
                      where every key is a taskId and the value is an array of
                      taskIds that must be completed before the key can be run
                    example:
                      550e8400-e29b-41d4-a716-446655440001: []
                      550e8400-e29b-41d4-a716-446655440002:
                        - 550e8400-e29b-41d4-a716-446655440001
                      550e8400-e29b-41d4-a716-446655440003:
                        - 550e8400-e29b-41d4-a716-446655440001
                      550e8400-e29b-41d4-a716-446655440004:
                        - 550e8400-e29b-41d4-a716-446655440002
                        - 550e8400-e29b-41d4-a716-446655440003
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  lastUpdatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - id
                  - accountId
                  - name
                  - description
                  - taskDag
                  - createdAt
                  - lastUpdatedAt
                description: A workflow in the system
        '400':
          description: Invalid request body
        '404':
          description: Account not found
    get:
      operationId: listWorkflows
      tags:
        - Workflows
      summary: List all workflows for an account
      description: Retrieves a list of all workflows associated with the specified account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
      responses:
        '200':
          description: List of workflows retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: The UUID of the workflow
                      example: 550e8400-e29b-41d4-a716-446655440000
                    accountId:
                      type: string
                      pattern: ^scd-[a-z0-9]{8}$
                      description: Short account ID with scd- prefix
                      example: scd-k2j8n4m1
                    name:
                      type: string
                      description: Name of the workflow
                      example: Document Processing Pipeline
                    description:
                      type: string
                      description: Description of the workflow
                      example: >-
                        A workflow that processes incoming documents through
                        categorization and metadata extraction
                    taskDag:
                      type: object
                      additionalProperties:
                        type: array
                        items:
                          type: string
                          format: uuid
                        description: Array of task IDs this task depends on
                      description: >-
                        Task dependency graph represented as an adjacency list,
                        where every key is a taskId and the value is an array of
                        taskIds that must be completed before the key can be run
                      example:
                        550e8400-e29b-41d4-a716-446655440001: []
                        550e8400-e29b-41d4-a716-446655440002:
                          - 550e8400-e29b-41d4-a716-446655440001
                        550e8400-e29b-41d4-a716-446655440003:
                          - 550e8400-e29b-41d4-a716-446655440001
                        550e8400-e29b-41d4-a716-446655440004:
                          - 550e8400-e29b-41d4-a716-446655440002
                          - 550e8400-e29b-41d4-a716-446655440003
                    createdAt:
                      type: string
                      format: date-time
                      example: '2024-01-15T10:30:00Z'
                    lastUpdatedAt:
                      type: string
                      nullable: true
                      format: date-time
                      example: '2024-01-15T14:30:00Z'
                  required:
                    - id
                    - accountId
                    - name
                    - description
                    - taskDag
                    - createdAt
                    - lastUpdatedAt
                  description: A workflow in the system
        '404':
          description: Account not found
  /accounts/{accountId}/workflows/{workflowId}:
    get:
      operationId: getWorkflow
      tags:
        - Workflows
      summary: Get a specific workflow by ID
      description: >-
        Retrieves detailed information about a specific workflow including its
        task DAG
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The UUID of the workflow
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          description: The UUID of the workflow
          name: workflowId
          in: path
      responses:
        '200':
          description: Workflow retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The UUID of the workflow
                    example: 550e8400-e29b-41d4-a716-446655440000
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    description: Short account ID with scd- prefix
                    example: scd-k2j8n4m1
                  name:
                    type: string
                    description: Name of the workflow
                    example: Document Processing Pipeline
                  description:
                    type: string
                    description: Description of the workflow
                    example: >-
                      A workflow that processes incoming documents through
                      categorization and metadata extraction
                  taskDag:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                        format: uuid
                      description: Array of task IDs this task depends on
                    description: >-
                      Task dependency graph represented as an adjacency list,
                      where every key is a taskId and the value is an array of
                      taskIds that must be completed before the key can be run
                    example:
                      550e8400-e29b-41d4-a716-446655440001: []
                      550e8400-e29b-41d4-a716-446655440002:
                        - 550e8400-e29b-41d4-a716-446655440001
                      550e8400-e29b-41d4-a716-446655440003:
                        - 550e8400-e29b-41d4-a716-446655440001
                      550e8400-e29b-41d4-a716-446655440004:
                        - 550e8400-e29b-41d4-a716-446655440002
                        - 550e8400-e29b-41d4-a716-446655440003
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  lastUpdatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - id
                  - accountId
                  - name
                  - description
                  - taskDag
                  - createdAt
                  - lastUpdatedAt
                description: A workflow in the system
        '404':
          description: Workflow not found
    put:
      operationId: updateWorkflow
      tags:
        - Workflows
      summary: Update an existing workflow
      description: >-
        Updates the properties of an existing workflow including name,
        description, and task DAG
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The UUID of the workflow
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          description: The UUID of the workflow
          name: workflowId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Name of the workflow
                  example: Updated Document Processing Pipeline
                description:
                  type: string
                  minLength: 1
                  description: Description of the workflow
                  example: Updated workflow description for document processing
                taskDag:
                  type: object
                  additionalProperties:
                    type: array
                    items:
                      type: string
                      format: uuid
                    description: Array of task IDs this task depends on
                  description: >-
                    Task dependency graph represented as an adjacency list,
                    where every key is a taskId and the value is an array of
                    taskIds that must be completed before the key can be run
                  example:
                    550e8400-e29b-41d4-a716-446655440001: []
                    550e8400-e29b-41d4-a716-446655440002:
                      - 550e8400-e29b-41d4-a716-446655440001
                    550e8400-e29b-41d4-a716-446655440003:
                      - 550e8400-e29b-41d4-a716-446655440001
                    550e8400-e29b-41d4-a716-446655440004:
                      - 550e8400-e29b-41d4-a716-446655440002
                      - 550e8400-e29b-41d4-a716-446655440003
              description: Data for updating a workflow
      responses:
        '200':
          description: Workflow updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The UUID of the workflow
                    example: 550e8400-e29b-41d4-a716-446655440000
                  accountId:
                    type: string
                    pattern: ^scd-[a-z0-9]{8}$
                    description: Short account ID with scd- prefix
                    example: scd-k2j8n4m1
                  name:
                    type: string
                    description: Name of the workflow
                    example: Document Processing Pipeline
                  description:
                    type: string
                    description: Description of the workflow
                    example: >-
                      A workflow that processes incoming documents through
                      categorization and metadata extraction
                  taskDag:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                        format: uuid
                      description: Array of task IDs this task depends on
                    description: >-
                      Task dependency graph represented as an adjacency list,
                      where every key is a taskId and the value is an array of
                      taskIds that must be completed before the key can be run
                    example:
                      550e8400-e29b-41d4-a716-446655440001: []
                      550e8400-e29b-41d4-a716-446655440002:
                        - 550e8400-e29b-41d4-a716-446655440001
                      550e8400-e29b-41d4-a716-446655440003:
                        - 550e8400-e29b-41d4-a716-446655440001
                      550e8400-e29b-41d4-a716-446655440004:
                        - 550e8400-e29b-41d4-a716-446655440002
                        - 550e8400-e29b-41d4-a716-446655440003
                  createdAt:
                    type: string
                    format: date-time
                    example: '2024-01-15T10:30:00Z'
                  lastUpdatedAt:
                    type: string
                    nullable: true
                    format: date-time
                    example: '2024-01-15T14:30:00Z'
                required:
                  - id
                  - accountId
                  - name
                  - description
                  - taskDag
                  - createdAt
                  - lastUpdatedAt
                description: A workflow in the system
        '400':
          description: Invalid request body
        '404':
          description: Workflow not found
    delete:
      operationId: deleteWorkflow
      tags:
        - Workflows
      summary: Delete a workflow
      description: Permanently deletes a workflow from the account
      parameters:
        - schema:
            type: string
            pattern: ^scd-[a-z0-9]{8}$
            description: Short account ID with scd- prefix
            example: scd-k2j8n4m1
          required: true
          description: Short account ID with scd- prefix
          name: accountId
          in: path
        - schema:
            type: string
            format: uuid
            description: The UUID of the workflow
            example: 550e8400-e29b-41d4-a716-446655440000
          required: true
          description: The UUID of the workflow
          name: workflowId
          in: path
      responses:
        '204':
          description: Workflow deleted successfully
        '404':
          description: Workflow not found
  /helpers/resolve-user-accounts:
    get:
      operationId: resolveUserAccounts
      description: >-
        Resolve all accounts associated with a given email address. Returns only
        account IDs for privacy.
      summary: Resolve user accounts by email
      tags:
        - Helpers
      parameters:
        - schema:
            type: string
            format: email
            example: user@example.com
          required: true
          name: email
          in: query
      responses:
        '200':
          description: Successfully resolved user accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    format: email
                    example: user@example.com
                  accounts:
                    type: array
                    items:
                      type: object
                      properties:
                        accountId:
                          type: string
                          pattern: ^scd-[a-z0-9]{8}$
                          description: Short account ID with scd- prefix
                          example: scd-k2j8n4m1
                      required:
                        - accountId
                      description: Public account information
                required:
                  - email
                  - accounts
        '400':
          description: Invalid query parameters
        '500':
          description: Internal server error
