# Authored by DotWin
# Generated by app/scripts/arp-mcp-tools.mjs from app/src/lib/developers/reference.ts. Do not edit by hand.
openapi: "3.1.0"
info:
  title: "ARKZ Human API"
  version: "1.2.0"
  description: "Every action is one POST of {\"action\": \"<name>\", ...} to one URL. health and get_ark_schema need no credential; every other action needs one: Authorization: Bearer <credential>, or x-ark-api-key. Early access actions answer only for an ARK enrolled in the ARK Record Protocol. Documentation: https://www.arkz.ai/developers"
servers:
  - url: "https://www.arkz.ai/api/human"
security:
  - bearer: []
  - apiKeyHeader: []
paths:
  "/":
    post:
      operationId: "callAction"
      summary: "Call one action"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/GetArkProfileRequest"
                - $ref: "#/components/schemas/SearchArkTopicsRequest"
                - $ref: "#/components/schemas/AskArkRequest"
                - $ref: "#/components/schemas/HealthRequest"
                - $ref: "#/components/schemas/GetArkSchemaRequest"
                - $ref: "#/components/schemas/ListArkRecordsRequest"
                - $ref: "#/components/schemas/GetArkRecordRequest"
                - $ref: "#/components/schemas/GetArkProvenanceRequest"
                - $ref: "#/components/schemas/ProposeArkRecordRequest"
                - $ref: "#/components/schemas/ProposeArkRecordsRequest"
                - $ref: "#/components/schemas/GetArkProposalStatusRequest"
              discriminator:
                propertyName: "action"
                mapping:
                  get_ark_profile: "#/components/schemas/GetArkProfileRequest"
                  search_ark_topics: "#/components/schemas/SearchArkTopicsRequest"
                  ask_ark: "#/components/schemas/AskArkRequest"
                  health: "#/components/schemas/HealthRequest"
                  get_ark_schema: "#/components/schemas/GetArkSchemaRequest"
                  list_ark_records: "#/components/schemas/ListArkRecordsRequest"
                  get_ark_record: "#/components/schemas/GetArkRecordRequest"
                  get_ark_provenance: "#/components/schemas/GetArkProvenanceRequest"
                  propose_ark_record: "#/components/schemas/ProposeArkRecordRequest"
                  propose_ark_records: "#/components/schemas/ProposeArkRecordsRequest"
                  get_ark_proposal_status: "#/components/schemas/GetArkProposalStatusRequest"
      responses:
        "200":
          description: "The action answer (see each action's example on /developers)."
          content:
            application/json:
              schema:
                type: "object"
        "400":
          description: "Refused: schema_invalid, hash_mismatch, verbatim_required, filter_invalid, invalid_input, invalid_cursor, unsupported_protocol_version."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Refused: unauthorized, entitlement_revoked."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Refused: grant_scope, subject_reserved, scope_missing, not_enabled, forbidden, source_key_forbidden, master_dormant."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Refused: not_found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "405":
          description: "Refused: method_not_allowed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413":
          description: "Refused: payload_too_large."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: "Refused: quota_exceeded, rate_limited."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: "Refused: server_error."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: "Refused: not_stored, not_recorded."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    bearer:
      type: "http"
      scheme: "bearer"
      description: "A credential: ark_live_, arka_, lic_, ark_src_"
    apiKeyHeader:
      type: "apiKey"
      in: "header"
      name: "x-ark-api-key"
  schemas:
    GetArkProfileRequest:
      type: "object"
      description: "Live. Credential scopes, any of: read:profile, read:stats. Metering: free. Codes: source_key_forbidden."
      required:
        - "action"
      properties:
        action:
          const: "get_ark_profile"
      examples:
        - action: "get_ark_profile"
    SearchArkTopicsRequest:
      type: "object"
      description: "Live. Credential scopes, any of: read:profile, read:stats. Metering: free. Codes: source_key_forbidden."
      required:
        - "action"
      properties:
        action:
          const: "search_ark_topics"
        query:
          type: "string"
          description: "Optional substring to filter topics (the first 500 characters are used)."
      examples:
        - action: "search_ark_topics"
          query: "pricing"
    AskArkRequest:
      type: "object"
      description: "Live. Credential scopes, any of: generate:text, generate:chat, generate:email, generate:social. Metering: billed_to_caller. Codes: source_key_forbidden."
      required:
        - "action"
        - "content"
      properties:
        action:
          const: "ask_ark"
        content:
          type: "string"
          description: "The question or prompt (REST; question is accepted as the same field, and MCP names it question). One question per call, no carried history."
        response_mode:
          type: "string"
          description: "Optional answer mode, passed to the ARK as given."
        output_type:
          type: "string"
          description: "Optional output type, passed to the ARK as given."
      examples:
        - action: "ask_ark"
          content: "What do you check first in a new plan?"
    HealthRequest:
      type: "object"
      description: "Live. No credential needed. Metering: free. Codes: none."
      required:
        - "action"
      properties:
        action:
          const: "health"
      examples:
        - action: "health"
    GetArkSchemaRequest:
      type: "object"
      description: "Early access. No credential needed. Metering: free. Codes: none."
      required:
        - "action"
      properties:
        action:
          const: "get_ark_schema"
      examples:
        - action: "get_ark_schema"
    ListArkRecordsRequest:
      type: "object"
      description: "Early access. Credential scopes, any of: read:records. Metering: free. Codes: scope_missing, filter_invalid."
      required:
        - "action"
      properties:
        action:
          const: "list_ark_records"
        filter:
          type: "object"
          description: "Optional. Narrows the records (it can never widen what the credential may read). Keys: facets, kinds, domains, topics, authorship, privacy, record_refs, status (lists), trust_min (T0 to T4), since, until (dates), provenance {owner_sources, documents, sessions, integrations, grants, credential_kinds}. Record format: https://www.arkz.ai/protocol/v0/record.schema.json"
        limit:
          type: "integer"
          description: "Page size, 1 to 100 (default 50)."
        after:
          type: "string"
          description: "The next_after value of the previous page."
      examples:
        - action: "list_ark_records"
          filter:
            facets:
              - "framework"
            trust_min: "T2"
          limit: 20
    GetArkRecordRequest:
      type: "object"
      description: "Early access. Credential scopes, any of: read:records. Metering: free. Codes: scope_missing, filter_invalid, not_found."
      required:
        - "action"
        - "record"
      properties:
        action:
          const: "get_ark_record"
        record:
          type: "string"
          description: "The record id (rec_<uuid>) or its ref."
      examples:
        - action: "get_ark_record"
          record: "rec_0f8e2a4c-6b1d-4e3f-9a7c-2d5b8e1f4a60"
    GetArkProvenanceRequest:
      type: "object"
      description: "Early access. Credential scopes, any of: read:records. Metering: free. Codes: scope_missing."
      required:
        - "action"
      properties:
        action:
          const: "get_ark_provenance"
      examples:
        - action: "get_ark_provenance"
    ProposeArkRecordRequest:
      type: "object"
      description: "Early access. Credential scopes, any of: write:proposals. Metering: free_at_intake_charged_at_acceptance. Codes: schema_invalid, hash_mismatch, verbatim_required, grant_scope, subject_reserved, scope_missing, not_enabled, quota_exceeded."
      required:
        - "action"
        - "envelope"
      properties:
        action:
          const: "propose_ark_record"
        envelope:
          $ref: "#/components/schemas/Envelope"
          description: "One ARK Record v0 envelope. provenance.content_sha256 is the lower-case hex SHA-256 of the canonical content and is recomputed by ARKZ. Record format: https://www.arkz.ai/protocol/v0/record.schema.json"
      examples:
        - action: "propose_ark_record"
          envelope:
            arp: "0"
            ark: "ark:arkz:3f6c1a52-8d4e-4b7a-9c2f-5e1d0a7b8c9d"
            facet: "framework"
            kind: "definition"
            authorship: "self_paraphrase"
            privacy: "training"
            content:
              text: "A keystone habit is one routine that pulls the rest of a plan along with it. Name it, guard it, and let the other habits hang from it."
            topics:
              - "habits"
              - "planning"
            provenance:
              content_sha256: "767df8399817b451238ab1075a2bc55a8eb9cc144aaad4a969814e528308dd5a"
              source_kind: "notes_app"
    ProposeArkRecordsRequest:
      type: "object"
      description: "Early access. Credential scopes, any of: write:proposals. Metering: free_at_intake_charged_at_acceptance. Codes: schema_invalid, hash_mismatch, verbatim_required, grant_scope, subject_reserved, scope_missing, not_enabled, quota_exceeded, not_stored."
      required:
        - "action"
        - "envelopes"
      properties:
        action:
          const: "propose_ark_records"
        envelopes:
          type: "array"
          minItems: 1
          items:
            $ref: "#/components/schemas/Envelope"
          description: "1 to 100 envelopes."
      examples:
        - action: "propose_ark_records"
          envelopes:
            - arp: "0"
              ark: "ark:arkz:3f6c1a52-8d4e-4b7a-9c2f-5e1d0a7b8c9d"
              facet: "experience_story"
              kind: "story"
              authorship: "self_paraphrase"
              content:
                text: "I priced my first workshop by asking three past clients what it had changed for them. Their answers set the price, not my nerves."
              domains:
                - "business"
              provenance:
                content_sha256: "a4e3655a5c16aee2aa907c5cea50a559205255ed1c54a3428cc20a258b5eeed0"
                source_kind: "interview_notes"
            - arp: "0"
              ark: "ark:arkz:3f6c1a52-8d4e-4b7a-9c2f-5e1d0a7b8c9d"
              facet: "knowledge"
              kind: "raw"
              authorship: "self_verbatim"
              content:
                text: "Q: What do you check first in a new plan?\nA: Who owns each step. If nobody owns it, it is not a step yet."
              provenance:
                content_sha256: "6f9e3498285055a9734c9634e4229be548989eb2e6877a7e41bda6f4c27ca69e"
                source_kind: "transcript"
                source_ref: "https://example.com/episodes/12"
    GetArkProposalStatusRequest:
      type: "object"
      description: "Early access. Credential scopes, any of: write:proposals. Metering: free. Codes: scope_missing, grant_scope, invalid_input, invalid_cursor, not_stored."
      required:
        - "action"
      properties:
        action:
          const: "get_ark_proposal_status"
        proposal_ids:
          type: "array"
          description: "1 to 100 proposal ids; the answer keeps their order."
        since:
          type: "string"
          description: "Listing only: proposals created at or after this time."
        limit:
          type: "integer"
          description: "Listing only: page size, 1 to 100 (default 50)."
        after:
          type: "string"
          description: "Listing only: the next value of the previous page."
      examples:
        - action: "get_ark_proposal_status"
          proposal_ids:
            - "0f8e2a4c-6b1d-4e3f-9a7c-2d5b8e1f4a60"
            - "6a1c9e3b-2f4d-4b8a-8e7c-1d3f5a9b7c20"
    Envelope:
      $ref: "https://www.arkz.ai/protocol/v0/record.schema.json"
    Error:
      type: "object"
      required:
        - "error"
      properties:
        error:
          type: "string"
          description: "A code from the error table, or for the three live actions a plain message."
        message:
          type: "string"
        code:
          type: "string"
          description: "Present on source_key_forbidden and on an entitlement refusal."