Developers

Quickstart

Five steps from a new key to a record you proposed, accepted and read back.

1. Make a key with the right scopes

Sign in and open the API keys settings page. An owner key made there carries the scopes you tick. When the protocol is on for your ARK, the same page makes an owner key that also holds read:records and write:proposals, the two protocol scopes. The key is shown once; keep it in a secret store.

API keys settings

2. Call get_ark_profile over REST

Send the action name in a JSON body with the key as a bearer credential. The answer is the public profile of the ARK the key is bound to.

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

3. Connect an MCP client

In any MCP client, add a remote server with the URL below, the Streamable HTTP transport and an Authorization header carrying the key. The client then lists the tools the key may call.

https://www.arkz.ai/mcp

Add a remote MCP server in your client.
Server URL: the URL above.
Transport: Streamable HTTP.
Header: Authorization: Bearer <your key>. A client that supports OAuth can sign in instead, through the discovery documents on the Authentication page.
Reload the client; it calls tools/list and shows the tools your credential may use.
A source key (ark_src_) cannot run an MCP session: initialize and tools/list answer -32003. A source uses REST, or sends bare tools/call messages for its three tools.

4. Propose a first record, then accept itEarly access

Send one record envelope with propose_ark_record. The proposal waits in the proposals panel of your Integration Hub. Open it, review the record and accept it. Nothing is charged before you accept.

curl -s https://www.arkz.ai/api/human \
  -H "Authorization: Bearer $ARKZ_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"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"}}}'

5. Read it backEarly access

Once accepted, the record is part of the ARK. List the records and find it by its facet and kind.

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

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