Developers
Reading an ARK
Ask the ARK a question, or read its records as protocol envelopes, always within the privacy ceiling of your credential.
The read tools
Each tool with its input, rendered from its definition. list_ark_records takes a filter object whose fields are listed in its input.
list_ark_recordsEarly access
A page of the connected ARK's records as protocol envelopes, within this credential's privacy ceiling (vault content is never returned). Needs the read:records scope. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
| Name | Type | Required | Limits | 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 | minimum 1, maximum 100 | Page size, 1 to 100 (default 50). |
after | string | no | The next_after value of the previous page. |
get_ark_recordEarly access
One record of the connected ARK as a protocol envelope, with its lineage. Needs the read:records scope. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
record | string | yes | The record id (rec_<uuid>) or its ref. |
get_ark_provenanceEarly access
Where the connected ARK's readable records came from, with counts: owner sources, documents, sessions, integrations, grants, credential kinds, trust tiers and authorship. Never a record's text. Needs the read:records scope. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
No parameters.
get_ark_schemaEarly access
The published ARK Record Protocol v0: the record and scope JSON Schemas, the facets and kinds, authorship, trust tiers, privacy and error codes. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
No parameters.
get_ark_profileLive
Get the connected ARK’s public profile: name, tagline, mastery level, primary domain, and how many shareable insights it has.
No parameters.
search_ark_topicsLive
Discover what the ARK knows: its topic coverage over shareable insights (no private/vault content is returned). Optionally filter by a substring.
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
query | string | no | Optional substring to filter topics. |
ask_arkLive
Ask the connected ARK a question and get a retrieval-augmented answer in the creator’s voice. Billable to the ARK owner.
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
question | string | yes | The question or prompt for the ARK. |
The privacy ceiling
| Credential | Reads |
|---|---|
| Owner key | records marked training or licensable; ask_ark answers from the public view |
| OAuth credential | records marked licensable; ask_ark answers from the public view |
| Licence credential | records marked licensable, in the facets the licence opens; ask_ark answers at the licensed level |
| Source key | nothing; a source key cannot read |
What is never served
The vault is never served by any credential. A record from a source the platform refuses to use for answers is not served either: every read passes the same source boundary the product applies.
Calling a derivativeEarly access
- A derivative made in the Derivative studio is its own ARK with its own id.
- A credential bound to it, an owner key made on a derivative you own or a licence credential for it, can call ask_ark. The answer is generated in the derivative's voice from the derivative's knowledge. An owner key bills the owner; a licence credential bills the licensee; a bounded derivative licence is covered by its allowance without a separate charge.
- One question per call. ask_ark carries no conversation history; pack any context into the question, which is capped at 4,000 characters.
- The knowledge is drawn from the derivative's Roots, filtered by the knowledge areas set in the studio. A record selection shown in the studio as a served count does not filter generation in v0. A derivative set to pinned or forked inheritance is served the snapshot taken when it was made: nothing added to the Root later reaches it, and a snapshot record leaves it when its Root record is removed, made vault or falls out of the knowledge areas.
- Vault records never reach a derivative; only records marked training or licensable do.
- list_ark_records, get_ark_record and get_ark_provenance read records whose ARK is the credential's ARK. A derivative's knowledge lives on its Roots, so a derivative credential reads no Root records through them.
- Older derivatives that live inside their Root as an overlay have no id of their own and cannot be addressed by the API.
No code: the website Agent
To put a derivative on a website without writing code, the owner enables the hosted website Agent for it in the studio. The owner lists the website origins allowed to embed it (up to 10) and sets a daily spending budget; the Agent stops answering once the daily budget is spent.