Arkova Attestations API

openapi: 3.2.0
info:
  title: Arkova Verification Attestations 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: Attestations
  description: Attestation claims (create, verify, revoke)
paths:
  /attestations:
    post:
      summary: Create attestation
      description: Create a new public attestation with optional evidence metadata. Collision retry (3x). Requires JWT or API key.
      operationId: createAttestation
      tags:
      - Attestations
      security:
      - SupabaseJWT: []
      - ApiKeyBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - attestation_type
              - attester_name
              - subject_identifier
              - claims
              properties:
                anchor_id:
                  type: string
                  format: uuid
                  description: Optional linked anchor UUID for owned credentials
                subject_type:
                  type: string
                  enum:
                  - credential
                  - entity
                  - process
                  - asset
                  default: credential
                subject_identifier:
                  type: string
                  description: Public ID or stable external identifier for the attestation subject
                attestation_type:
                  type: string
                  enum:
                  - VERIFICATION
                  - ENDORSEMENT
                  - AUDIT
                  - APPROVAL
                  - WITNESS
                  - COMPLIANCE
                  - SUPPLY_CHAIN
                  - IDENTITY
                  - CUSTOM
                attester_name:
                  type: string
                attester_type:
                  type: string
                  enum:
                  - INSTITUTION
                  - CORPORATION
                  - INDIVIDUAL
                  - REGULATORY
                  - THIRD_PARTY
                  default: INSTITUTION
                attester_title:
                  type: string
                claims:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    required:
                    - claim
                    properties:
                      claim:
                        type: string
                      evidence:
                        type: string
                summary:
                  type: string
                jurisdiction:
                  type: string
                evidence_fingerprint:
                  type: string
                  pattern: ^[a-fA-F0-9]{64}$
                evidence:
                  type: array
                  maxItems: 10
                  description: Evidence metadata only. Arkova stores public metadata and fingerprints, not document bytes.
                  items:
                    $ref: '#/components/schemas/AttestationEvidenceInput'
                expires_at:
                  type:
                  - string
                  - 'null'
                  format: date-time
                metadata:
                  $ref: '#/components/schemas/AttestationMetadataInput'
      responses:
        '201':
          description: Attestation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAttestationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      summary: List attestations
      description: List attestations. Supports cursor-based pagination.
      operationId: listAttestations
      tags:
      - Attestations
      security: []
      parameters:
      - name: anchor_id
        in: query
        schema:
          type: string
          format: uuid
        description: Filter by linked anchor UUID for owned credentials
      - name: subject_identifier
        in: query
        schema:
          type: string
        description: Filter by subject public ID or external identifier
      - name: attestation_type
        in: query
        schema:
          type: string
        description: Filter by attestation type
      - name: status
        in: query
        schema:
          type: string
        description: Filter by status
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor (opaque string from previous response)
      - name: page
        in: query
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Paginated attestation list
          content:
            application/json:
              schema:
                type: object
                properties:
                  attestations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Attestation'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                  has_more:
                    type: boolean
  /attestations/{publicId}:
    get:
      summary: Get attestation
      description: Retrieve a single public attestation. Omit include to receive the default response shape; pass include=credentials to add a bounded attestor credential chain.
      operationId: getAttestation
      tags:
      - Attestations
      security: []
      parameters:
      - name: publicId
        in: path
        required: true
        schema:
          type: string
          minLength: 3
      - name: include
        in: query
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - credentials
        description: Optional comma-separated include list. Use credentials to include attestor_credentials, capped at the current linked credential plus two parent levels.
      responses:
        '200':
          description: Attestation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attestation'
        '404':
          $ref: '#/components/responses/NotFound'
  /attestations/{publicId}/revoke:
    patch:
      summary: Revoke attestation
      description: Revoke an attestation. Requires ownership (JWT or API key that created it).
      operationId: revokeAttestation
      tags:
      - Attestations
      security:
      - SupabaseJWT: []
      - ApiKeyBearer: []
      parameters:
      - name: publicId
        in: path
        required: true
        schema:
          type: string
          minLength: 3
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
      responses:
        '200':
          description: Attestation revoked
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Already revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /attestations/batch-create:
    post:
      summary: Create attestations in batch
      description: Create up to 100 attestations in one request. Requires JWT. Each item is inserted individually (public_id collision retry, 3x); a per-item failure does not fail the batch. Costs no AI credits — metadata is only available when ENABLE_AI_EXTRACTION is on (503 if any item carries metadata while the flag is off).
      operationId: batchCreateAttestations
      tags:
      - Attestations
      security:
      - SupabaseJWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - attestations
              properties:
                attestations:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    required:
                    - attestation_type
                    - attester_name
                    - subject_identifier
                    - claims
                    description: Same shape as the POST /attestations request body.
      responses:
        '201':
          description: Batch processed (per-item success/failure — HTTP 201 even with partial failures)
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        public_id:
                          type: string
                        status:
                          type: string
                        fingerprint:
                          type: string
                        evidence_count:
                          type: integer
                        warning:
                          type: string
                        error:
                          type: string
                  summary:
                    type: object
                    properties:
                      total:
                        type: integer
                      created:
                        type: integer
                      failed:
                        type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          description: Attestation metadata supplied while ENABLE_AI_EXTRACTION is off
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /attestations/batch-verify:
    post:
      summary: Verify attestations in batch
      description: Look up verification status for up to 100 public IDs in one request. Requires an API key with verify:batch scope.
      operationId: batchVerifyAttestations
      tags:
      - Attestations
      x-arkova-required-scopes:
      - verify:batch
      security:
      - ApiKeyBearer: []
      - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - public_ids
              properties:
                public_ids:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    minLength: 3
      responses:
        '200':
          description: Per-ID verification results with a summary tally
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        public_id:
                          type: string
                        found:
                          type: boolean
                        status:
                          type: string
                        attestation_type:
                          type: string
                        subject_identifier:
                          type: string
                        attester:
                          type:
                          - object
                          - 'null'
                          properties:
                            name:
                              type: string
                            type:
                              type: string
                        issued_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        expires_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        chain_proof:
                          type:
                          - object
                          - 'null'
                          properties:
                            tx_id:
                              type: string
                            block_height:
                              type:
                              - integer
                              - 'null'
                            timestamp:
                              type:
                              - string
                              - 'null'
                              format: date-time
                            explorer_url:
                              type:
                              - string
                              - 'null'
                  summary:
                    type: object
                    properties:
                      total:
                        type: integer
                      verified:
                        type: integer
                      not_found:
                        type: integer
                      expired:
                        type: integer
                      revoked:
                        type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    AttestationEvidenceInput:
      type: object
      additionalProperties: false
      required:
      - evidence_type
      - fingerprint
      properties:
        evidence_type:
          type: string
          maxLength: 60
          default: document
        fingerprint:
          type: string
          pattern: ^[a-fA-F0-9]{64}$
          description: SHA-256 evidence artifact fingerprint
        mime:
          type:
          - string
          - 'null'
          maxLength: 255
        size:
          type:
          - integer
          - 'null'
          minimum: 0
        filename:
          type:
          - string
          - 'null'
          maxLength: 255
          description: Public-safe evidence filename metadata only
        description:
          type:
          - string
          - 'null'
          maxLength: 500
          description: Public-safe evidence description metadata only
    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
    CreateAttestationResponse:
      type: object
      required:
      - public_id
      - attestation_id
      - attestation_type
      - status
      - fingerprint
      - created_at
      - verify_url
      properties:
        public_id:
          type: string
        attestation_id:
          type: string
          description: v1 back-compat alias for public_id; never an internal UUID
        attestation_type:
          type: string
        status:
          type: string
          enum:
          - PENDING
        fingerprint:
          type: string
          pattern: ^[a-fA-F0-9]{64}$
        created_at:
          type: string
          format: date-time
        verify_url:
          type: string
          format: uri
        evidence_count:
          type: integer
          minimum: 0
        warning:
          type: string
    AttestationEvidence:
      type: object
      required:
      - id
      - public_id
      - evidence_type
      - fingerprint
      - created_at
      properties:
        id:
          type: string
          pattern: ^AEV-[A-F0-9]{32}$
          description: v1 back-compat alias for public_id; never an internal UUID
        public_id:
          type: string
          pattern: ^AEV-[A-F0-9]{32}$
        evidence_type:
          type: string
        description:
          type:
          - string
          - 'null'
        fingerprint:
          type: string
          pattern: ^[a-fA-F0-9]{64}$
        mime:
          type:
          - string
          - 'null'
        size:
          type:
          - integer
          - 'null'
          minimum: 0
        created_at:
          type: string
          format: date-time
    AttestationMetadataInput:
      type: object
      additionalProperties: false
      description: Optional PII-stripped metadata. Accepted only when ENABLE_AI_EXTRACTION is enabled.
      properties:
        template:
          type: string
          maxLength: 80
        credential_type:
          type: string
          maxLength: 100
        credential_sub_type:
          type: string
          maxLength: 100
        document_type:
          type: string
          maxLength: 100
        issuer_name:
          type: string
          maxLength: 200
        issuing_jurisdiction:
          type: string
          maxLength: 100
        issued_date:
          type: string
          maxLength: 40
        expiration_date:
          type: string
          maxLength: 40
        extraction_provider:
          type: string
          maxLength: 80
        extraction_confidence:
          type: number
          minimum: 0
          maximum: 1
        metadata_fingerprint:
          type: string
          pattern: ^[a-fA-F0-9]{64}$
    Attestation:
      type: object
      required:
      - public_id
      - attestation_type
      - status
      - subject_type
      - subject_identifier
      - attester
      - claims
      - evidence
      - evidence_count
      - created_at
      - verify_url
      properties:
        public_id:
          type: string
        attestation_type:
          type: string
          enum:
          - VERIFICATION
          - ENDORSEMENT
          - AUDIT
          - APPROVAL
          - WITNESS
          - COMPLIANCE
          - SUPPLY_CHAIN
          - IDENTITY
          - CUSTOM
        status:
          type: string
        subject_type:
          type: string
          enum:
          - credential
          - entity
          - process
          - asset
        subject_identifier:
          type: string
        subject:
          type: object
          deprecated: true
          description: Deprecated v1 compatibility object mirroring subject_type and subject_identifier.
          properties:
            type:
              type: string
              enum:
              - credential
              - entity
              - process
              - asset
            identifier:
              type: string
        attester:
          type: object
          required:
          - name
          - type
          properties:
            name:
              type: string
            type:
              type: string
              enum:
              - INSTITUTION
              - CORPORATION
              - INDIVIDUAL
              - REGULATORY
              - THIRD_PARTY
            title:
              type:
              - string
              - 'null'
            kind:
              type: string
              enum:
              - organization
              - individual
              description: 'UAT-26: organization = made on behalf of an organization by one of its administrators; individual = one person''s own statement (always type INDIVIDUAL). Name, type and title are as entered by the attester.'
        claims:
          type: array
          items:
            type: object
            required:
            - claim
            properties:
              claim:
                type: string
              evidence:
                type: string
        summary:
          type:
          - string
          - 'null'
        jurisdiction:
          type: string
          description: Omitted when null, never returned as null
        fingerprint:
          type:
          - string
          - 'null'
          pattern: ^[a-fA-F0-9]{64}$
        evidence_fingerprint:
          type:
          - string
          - 'null'
          pattern: ^[a-fA-F0-9]{64}$
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/AttestationEvidence'
        evidence_count:
          type: integer
          minimum: 0
        chain_proof:
          type:
          - object
          - 'null'
          properties:
            tx_id:
              type: string
            block_height:
              type:
              - integer
              - 'null'
            timestamp:
              type:
              - string
              - 'null'
              format: date-time
            explorer_url:
              type:
              - string
              - 'null'
              format: uri
        anchored_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Deprecated v1 alias for chain_proof.timestamp
        merkle_root:
          type:
          - string
          - 'null'
          description: Deprecated v1 alias for the chain Merkle root when available
        linked_credential:
          type:
          - object
          - 'null'
          properties:
            public_id:
              type: string
            credential_type:
              type:
              - string
              - 'null'
            verification_status:
              type: string
            verify_url:
              type: string
              format: uri
        attestor_credentials:
          type: array
          description: Present only with include=credentials. Capped at the current linked credential plus two parent levels.
          items:
            $ref: '#/components/schemas/AttestorCredential'
        issued_at:
          type:
          - string
          - 'null'
          format: date-time
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
        revoked_at:
          type:
          - string
          - 'null'
          format: date-time
        revocation_reason:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        verify_url:
          type: string
          format: uri
    AttestorCredential:
      type: object
      required:
      - public_id
      - status
      - is_current
      - chain_proof
      - record_uri
      properties:
        public_id:
          type: string
        credential_type:
          type:
          - string
          - 'null'
        status:
          type: string
        fingerprint:
          type:
          - string
          - 'null'
        version_number:
          type:
          - integer
          - 'null'
        parent_public_id:
          type:
          - string
          - 'null'
        is_current:
          type: boolean
        chain_proof:
          type:
          - object
          - 'null'
          properties:
            tx_id:
              type: string
            block_height:
              type:
              - integer
              - 'null'
            timestamp:
              type:
              - string
              - 'null'
              format: date-time
            explorer_url:
              type:
              - string
              - 'null'
              format: uri
        record_uri:
          type: string
          format: uri
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until retry is allowed
      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