Developers

REST reference

One endpoint. POST a JSON body that names the action and carries its parameters at the top level.

The request is {"action": name, ...parameters}. A success is HTTP 200 with the action result as the body; the protocol actions carry "arp": "0". A failure is a non-200 status with an error body (see Errors).

curl -s https://www.arkz.ai/api/human \
  -H "Authorization: Bearer $ARKZ_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"get_ark_profile"}'

Every action

get_ark_profileLive

Field	Value
REST	credential
Scopes (any one)	read:profile, read:stats
Source key	no
Metering	Free
Errors	`source_key_forbidden`

Request

{
  "action": "get_ark_profile"
}

Response

{
  "ark": {
    "id": "3f6c1a52-8d4e-4b7a-9c2f-5e1d0a7b8c9d",
    "name": "Dana Reyes",
    "tagline": "Plans that ship",
    "avatar_url": null,
    "mastery_level": "Advanced",
    "level": 4,
    "settled_xp": 8000,
    "ark_fidelity": 510,
    "fidelity_band": "Verified",
    "score_status": "ready",
    "primary_domain": "business",
    "trainable_insights": 412,
    "marketplace": null
  }
}

search_ark_topicsLive

Field	Value
REST	credential
Scopes (any one)	read:profile, read:stats
Source key	no
Metering	Free
Errors	`source_key_forbidden`

Name	Type	Required	Description
`query`	`string`	no	Optional substring to filter topics (the first 500 characters are used).

Request

{
  "action": "search_ark_topics",
  "query": "pricing"
}

Response

{
  "topics": [
    {
      "topic": "pricing",
      "insight_count": 14
    }
  ],
  "total_shareable_insights": 412
}

ask_arkLive

Field	Value
REST	credential
Scopes (any one)	generate:text, generate:chat, generate:email, generate:social
Source key	no
Metering	Billed to the account behind the credential: the ARK owner's wallet for an owner key or OAuth; the licensee's licence quota and overage for a licence; covered by the allowance for a derivative licence
Errors	`source_key_forbidden`

Name	Type	Required	Description
`content`	`string`	yes	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`	`string`	no	Optional answer mode, passed to the ARK as given.
`output_type`	`string`	no	Optional output type, passed to the ARK as given.

Request

{
  "action": "ask_ark",
  "content": "What do you check first in a new plan?"
}

Response

{
  "ark_id": "3f6c1a52-8d4e-4b7a-9c2f-5e1d0a7b8c9d",
  "answer": "Who owns each step. If nobody owns it, it is not a step yet.",
  "model": "(the model id that answered)",
  "usage": {
    "usage_id": "9b2d4f6a-1c3e-4a5b-8d7f-0e2a4c6b8d10",
    "cost_cents": "(the charge in cents, an integer; 0 when a licence allowance covers it)",
    "billing_status": "(metered, billed_overage or covered_subscription)"
  }
}

healthLive

Field	Value
REST	no credential
Scopes (any one)	none
Source key	no
Metering	Free
Errors	none

Request

{
  "action": "health"
}

Response

{
  "status": "ok",
  "service": "ark-api",
  "version": "1.2.0"
}

get_ark_schemaEarly access

Field	Value
REST	no credential
Scopes (any one)	none
Source key	no
Metering	Free
Errors	none

Request

{
  "action": "get_ark_schema"
}

Response

{
  "arp": "0",
  "record_schema": "(RECORD_SCHEMA)",
  "scope_schema": "(SCOPE_SCHEMA)",
  "error_codes": {
    "write": "(ERROR_CODES)",
    "read": "(READ_ERROR_CODES)"
  }
}

list_ark_recordsEarly access

Field	Value
REST	credential
Scopes (any one)	read:records
Source key	no
Metering	Free
Errors	`scope_missing, filter_invalid`

Name	Type	Required	Description
`filter`	`object`	no	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`	`integer`	no	Page size, 1 to 100 (default 50).
`after`	`string`	no	The next_after value of the previous page.

Request

{
  "action": "list_ark_records",
  "filter": {
    "facets": [
      "framework"
    ],
    "trust_min": "T2"
  },
  "limit": 20
}

Response

{
  "arp": "0",
  "records": [
    "(ARK Record v0 envelopes)"
  ],
  "next_after": null
}

get_ark_recordEarly access

Field	Value
REST	credential
Scopes (any one)	read:records
Source key	no
Metering	Free
Errors	`scope_missing, filter_invalid, not_found`

Name	Type	Required	Description
`record`	`string`	yes	The record id (rec_<uuid>) or its ref.

Request

{
  "action": "get_ark_record",
  "record": "rec_0f8e2a4c-6b1d-4e3f-9a7c-2d5b8e1f4a60"
}

Response

{
  "arp": "0",
  "record": "(one ARK Record v0 envelope, with its lineage)"
}

get_ark_provenanceEarly access

Field	Value
REST	credential
Scopes (any one)	read:records
Source key	no
Metering	Free
Errors	`scope_missing`

Request

{
  "action": "get_ark_provenance"
}

Response

{
  "arp": "0",
  "provenance": [
    "(counts by owner source, document, session, integration, grant, credential kind, trust tier and authorship)"
  ]
}

propose_ark_recordEarly access

Field	Value
REST	credential
Scopes (any one)	write:proposals
Source key	yes
Metering	Free at intake, charged at acceptance as one ingested insight on the owner's plan
Errors	`schema_invalid, hash_mismatch, verbatim_required, grant_scope, subject_reserved, scope_missing, not_enabled, quota_exceeded`

Name	Type	Required	Description
`envelope`	`object`	yes	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

Request

{
  "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"
    }
  }
}

Response

{
  "arp": "0",
  "proposal_id": "0f8e2a4c-6b1d-4e3f-9a7c-2d5b8e1f4a60",
  "status": "proposed",
  "lane": "typed"
}

propose_ark_recordsEarly access

Field	Value
REST	credential
Scopes (any one)	write:proposals
Source key	yes
Metering	Free at intake, charged at acceptance as one ingested insight on the owner's plan
Errors	`schema_invalid, hash_mismatch, verbatim_required, grant_scope, subject_reserved, scope_missing, not_enabled, quota_exceeded, not_stored`

Name	Type	Required	Description
`envelopes`	`array`	yes	1 to 100 envelopes.

Request

{
  "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"
      }
    }
  ]
}

Response

{
  "arp": "0",
  "results": [
    {
      "index": 0,
      "proposal_id": "6a1c9e3b-2f4d-4b8a-8e7c-1d3f5a9b7c20",
      "status": "proposed",
      "lane": "typed"
    },
    {
      "index": 1,
      "status": "duplicate",
      "duplicate_of": "0f8e2a4c-6b1d-4e3f-9a7c-2d5b8e1f4a60"
    }
  ]
}

get_ark_proposal_statusEarly access

Field	Value
REST	credential
Scopes (any one)	write:proposals
Source key	yes
Metering	Free
Errors	`scope_missing, grant_scope, invalid_input, invalid_cursor, not_stored`

Name	Type	Required	Description
`proposal_ids`	`array`	no	1 to 100 proposal ids; the answer keeps their order.
`since`	`string`	no	Listing only: proposals created at or after this time.
`limit`	`integer`	no	Listing only: page size, 1 to 100 (default 50).
`after`	`string`	no	Listing only: the next value of the previous page.

Request

{
  "action": "get_ark_proposal_status",
  "proposal_ids": [
    "0f8e2a4c-6b1d-4e3f-9a7c-2d5b8e1f4a60",
    "6a1c9e3b-2f4d-4b8a-8e7c-1d3f5a9b7c20"
  ]
}

Response

{
  "proposals": [
    {
      "proposal_id": "0f8e2a4c-6b1d-4e3f-9a7c-2d5b8e1f4a60",
      "status": "accepted",
      "created_at": "2026-10-06T14:02:11Z",
      "decided_at": "2026-10-06T16:40:03Z"
    },
    {
      "proposal_id": "6a1c9e3b-2f4d-4b8a-8e7c-1d3f5a9b7c20",
      "status": "not_found"
    }
  ]
}

OpenAPI

The same actions as an OpenAPI 3.1 document: /developers/openapi.yaml

Licensed for use, not for copying: you may not use this ARK's output to train, build or populate another ARK, model or dataset.

REST reference

The endpoint

Request and response

Every action

get_ark_profileLive

search_ark_topicsLive

ask_arkLive

healthLive

get_ark_schemaEarly access

list_ark_recordsEarly access

get_ark_recordEarly access

get_ark_provenanceEarly access

propose_ark_recordEarly access

propose_ark_recordsEarly access

get_ark_proposal_statusEarly access

OpenAPI

Your wallet on this device

Your wallet, your choice