Arkova Folders API

openapi: 3.2.0
info:
  title: Arkova Verification Folders API
  version: 1.0.1
  description: Programmatic credential verification API. Verify credentials anchored on the Bitcoin network. Worker-generated v1 JSON errors expose common top-level code and message fields. The legacy error field is retained unchanged (string or object), along with details and quota context, for existing integrations. Parse code and message for new integrations. Upstream gateway errors may not be JSON. Revision 1.0.1 restores legacy label and DIPLOMA inputs and clarifies receipts and webhook payloads; the endpoint version remains v1.
  contact:
    name: Arkova Support
    url: https://arkova.ai
servers:
- url: /api/v1
  description: Verification API v1
security:
- ApiKeyBearer: []
- ApiKeyHeader: []
tags:
- name: Folders
  description: Nested personal and organization record folders
paths:
  /folders:
    get:
      summary: List canonical record folders
      operationId: listFolders
      tags:
      - Folders
      x-arkova-required-scopes:
      - anchor:read
      security:
      - ApiKeyHeader: []
      - SupabaseJWT: []
      description: Lists one USER or ORG folder tree. Global personal folders are private to their owner. A personal folder with context_org_id is visible to authorized administrators of that approved organization hierarchy. Organization API keys can access only their key organization context.
      parameters:
      - name: owner_scope
        in: query
        schema:
          type: string
          enum:
          - USER
          - ORG
      - name: owner_user_id
        in: query
        schema:
          type: string
          format: uuid
      - name: org_id
        in: query
        schema:
          type: string
          format: uuid
      - name: context_org_id
        in: query
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Folder tree rows
          content:
            application/json:
              schema:
                type: object
                required:
                - folders
                properties:
                  folders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      summary: Create a folder or subfolder
      operationId: createFolder
      tags:
      - Folders
      x-arkova-required-scopes:
      - anchor:write
      security:
      - ApiKeyHeader: []
      - SupabaseJWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - owner_scope
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                owner_scope:
                  type: string
                  enum:
                  - USER
                  - ORG
                org_id:
                  type:
                  - string
                  - 'null'
                  format: uuid
                context_org_id:
                  type:
                  - string
                  - 'null'
                  format: uuid
                parent_folder_id:
                  type:
                  - string
                  - 'null'
                  format: uuid
      responses:
        '201':
          description: Folder created
          content:
            application/json:
              schema:
                type: object
                properties:
                  folder:
                    $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /folders/member-context:
    get:
      summary: Read an authorized organization member context
      operationId: getFolderMemberContext
      tags:
      - Folders
      security:
      - SupabaseJWT: []
      description: Internal dashboard drill-down. Requires an AAL2 user session and exact or approved-ancestor organization administration. API keys are rejected. Membership is derived from org_members; a profiles.org_id value alone never grants access.
      parameters:
      - name: owner_user_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: context_org_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Bounded member identity in the requested membership context
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /folders/member-contexts:
    get:
      summary: List authorized organization member contexts
      operationId: listFolderMemberContexts
      tags:
      - Folders
      security:
      - SupabaseJWT: []
      description: Internal AAL2 dashboard roster derived from exact org_members rows. API keys are rejected.
      parameters:
      - name: context_org_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Bounded exact-membership roster
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /folders/{folderId}:
    patch:
      summary: Rename or reparent a folder
      operationId: updateFolder
      tags:
      - Folders
      x-arkova-required-scopes:
      - anchor:write
      security:
      - ApiKeyHeader: []
      - SupabaseJWT: []
      parameters:
      - name: folderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                parent_folder_id:
                  type:
                  - string
                  - 'null'
                  format: uuid
      responses:
        '200':
          description: Folder updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  folder:
                    $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete an empty folder
      operationId: deleteFolder
      tags:
      - Folders
      x-arkova-required-scopes:
      - anchor:write
      security:
      - ApiKeyHeader: []
      - SupabaseJWT: []
      parameters:
      - name: folderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Folder deleted; its records become Unfiled
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Folder still has child folders
  /folders/{folderId}/connector:
    put:
      summary: Bind or clear a connector auto-sort destination
      operationId: bindFolderConnector
      tags:
      - Folders
      x-arkova-required-scopes:
      - anchor:write
      security:
      - ApiKeyHeader: []
      - SupabaseJWT: []
      description: The connection must be active, owned by the same organization or contextual member, and match the provider. Set all three properties to null to clear the binding.
      parameters:
      - name: folderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - provider
              - source_id
              - connection_id
              properties:
                provider:
                  type:
                  - string
                  - 'null'
                  enum:
                  - google_drive
                  - docusign
                  - null
                source_id:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  maxLength: 500
                connection_id:
                  type:
                  - string
                  - 'null'
                  format: uuid
      responses:
        '200':
          description: Connector destination updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  folder:
                    $ref: '#/components/schemas/Folder'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Connector source already has a canonical destination
  /folders/bulk-move:
    post:
      summary: Move up to 100 records with partial results
      operationId: bulkMoveFolderRecords
      tags:
      - Folders
      x-arkova-required-scopes:
      - anchor:write
      security:
      - ApiKeyHeader: []
      - SupabaseJWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - folder_id
              oneOf:
              - required:
                - anchor_ids
              - required:
                - record_public_ids
              properties:
                anchor_ids:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    format: uuid
                  description: Internal UUID compatibility input for dashboard clients.
                record_public_ids:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    pattern: ^ARK-
                  description: API-visible record public ids. Outcomes preserve these identifiers.
                folder_id:
                  type:
                  - string
                  - 'null'
                  format: uuid
                  description: Null moves records to Unfiled.
      responses:
        '200':
          description: Every record moved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderMoveResult'
        '207':
          description: Authorized records moved; rejected rows are listed independently
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderMoveResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          oneOf:
          - type: string
          - type: object
            additionalProperties: true
            properties:
              code:
                type: string
              message:
                type: string
        code:
          type: string
          description: Common machine-readable error code; legacy error remains unchanged.
        message:
          type: string
    FolderMoveResult:
      type: object
      required:
      - moved
      - failed
      properties:
        moved:
          type: array
          items:
            oneOf:
            - type: string
              format: uuid
            - type: string
              pattern: ^ARK-
        failed:
          type: array
          items:
            type: object
            required:
            - anchor_id
            - code
            properties:
              anchor_id:
                oneOf:
                - type: string
                  format: uuid
                - type: string
                  pattern: ^ARK-
              code:
                type: string
    Folder:
      type: object
      required:
      - id
      - public_id
      - name
      - owner_scope
      - created_at
      - updated_at
      properties:
        id:
          type: string
          format: uuid
        public_id:
          type: string
          pattern: ^FLD-[A-F0-9]{16}$
        name:
          type: string
        owner_scope:
          type: string
          enum:
          - USER
          - ORG
        user_id:
          type:
          - string
          - 'null'
          format: uuid
        org_id:
          type:
          - string
          - 'null'
          format: uuid
        context_org_id:
          type:
          - string
          - 'null'
          format: uuid
        parent_folder_id:
          type:
          - string
          - 'null'
          format: uuid
        connector_provider:
          type:
          - string
          - 'null'
          enum:
          - google_drive
          - docusign
          - null
        connector_source_id:
          type:
          - string
          - 'null'
        connector_connection_id:
          type:
          - string
          - 'null'
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: 'API key as Bearer token: `Authorization: Bearer ak_live_...`'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key via header: `X-API-Key: ak_live_...`'
    SupabaseJWT:
      type: http
      scheme: bearer
      description: Supabase JWT for key management endpoints