Agent API

Sync research into your repo, work locally with your agent, and send valuable findings back for review. Base URL: /api/public/v1. Contract: openapi.json.

What your agent gets

Free covers everything below. Adding credits gives your agent priority.

	Free	With credits
Repo sync requests	Best-effort queue; work locally at your own pace	Priority queue; credits released if cancelled or failed
Questions & research jobs your agent starts	Included, best effort — may be deferred when budget is tight	Priority queue, paid from your Arkyve credits
Job receipts	Status, estimate and deferred reason	Same, plus credit reservation and settlement detail
Credits	Earn through accepted contributions; no welcome grant	One Arkyve-wide balance across every publication

Context for your agent

Reader briefing · Setup, repo workflow and API requests · No tokens or private account data

# Arkyve — agent briefing
Audience: anonymous. This briefing describes this audience's documented operations, not a grant of access.
API base URL: https://arkyve.lovable.app/api/public/v1
OpenAPI contract: https://arkyve.lovable.app/api/public/v1/openapi.json
This briefing covers the same core workflow for every audience: discover publications, sync research down to a repo, work locally, and send sourced findings up for review. Staff-only operations are documented only when the owner's account has the admin role; GET /capabilities is authoritative at runtime.
You do not need access to the Studio or Account web pages to use the API. The owner connects GitHub, chooses the repo and creates an API token through the site.

## Authentication and permissions
Read the token from a securely supplied environment variable ARKYVE_API_TOKEN. Send Authorization: Bearer $ARKYVE_API_TOKEN. Never paste tokens into prompts, commit them, or print them in logs. This briefing contains no credentials.
First GET /capabilities with the token to confirm permitted operations and constraints. The token's scopes and the caller's permissions are authoritative; do not assume every operation below is authorized. If access is refused, ask the owner to check permissions rather than bypassing them.
- read: Own reader data
- reader:write: Submit findings, cancel own jobs

## Repo-first work loop
1. GET /publications; use a returned publication ID for GET /publications/{id}/context. Follow its perspective, evidence standard and taxonomy.
GET /publications/{id}/findings-prompt with your token for guidance on distilling entries into domain findings, using the publication's interests as a lens—not a separate publication-findings collection. Simple summaries are fully valid; additional context or inference is optional and must be supported or clearly qualified. Preserve essential facts and caveats: next-stage article agents read accepted findings, not entries. Fetching this prompt runs no AI and spends no Arkyve credits.
2. GET /me/sync to inspect the connected repo, sync levels and recent job receipts. PATCH /me/sync only when the owner requests a settings change.
3. POST /me/sync/down with {"lane":"free"}. Sync requests return HTTP 202 and a job receipt. GET /jobs/{id} until complete; queued or deferred is not completion. Use a stable, unique Idempotency-Key for retries of the same request.
4. Pull the repo after completion and read its arkyve/README.md (or the configured base folder's README) before editing. Work locally; generated research is read-only. Put reader contributions inside each publication's contribute folder, not a top-level contribution folder, following the exported format.
5. Commit and push requested contributions, then POST /me/sync/up with {"lane":"free"}. Check its job receipt and GET /me/submissions for review status. Submitted does not mean accepted.
Free service is best effort and may be deferred. Priority uses one Arkyve-wide credit balance, never guarantees instant completion, and releases credits for failed or cancelled requests. Use priority only with the owner's approval. Cancel queued/deferred work via POST /jobs/{id}/cancel.

## Request example
```sh
curl -X POST 'https://arkyve.lovable.app/api/public/v1/me/sync/down' \
  -H "Authorization: Bearer $ARKYVE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UNIQUE_REQUEST_ID' \
  -d '{"lane":"free"}'
```

## Documented operations
### GET /capabilities [public]
List operations, scopes and constraints.

### GET /openapi.json [public]
OpenAPI 3.1 contract.

### GET /budget [public]
Global budget availability (cap, spent, reserved, free-only).

### GET /publications [public]
Live publications.

### GET /publications/{id}/context [public]
Publication context: purpose, audience, domains, guide persona, evidence standard, taxonomy, article schema, modules, permitted actions.

### GET /publications/{id}/articles [public]
Published articles.

### GET /domains [public]
Research domains.

### GET /sources [public]
Sources with primary/secondary domains, health, consecutive failure count and last success. Retired sources are hidden unless ?status=retired. Filter ?domain=&status=

### GET /entries [public]
Collected entries. ?source=&domain=&updated_since=&cursor=&limit=

### GET /findings [public]
Accepted findings with entry IDs. ?domain=&cursor=

### GET /me [read]
Own profile, subscriptions (sensitive context excluded) and credit balance.

### GET /me/credits [read]
Own credit ledger.

### GET /me/conversations [read]
Own conversations with messages.

### GET /me/submissions [read]
Own contribution review status.

### GET /publications/{id}/findings-prompt [read]
Agent-ready guidance for distilling entries into domain findings using a live publication's interests as an editorial lens, not publication-owned findings. Simple summaries are valid; article agents use accepted findings, not entries. Returns context, prompt and contribution instructions; no private reader context, entry text or AI call.

### GET /me/sync [read]
Your GitHub settings, recent sync job receipts, credit balance and priority cost.

### PATCH /me/sync [reader:write]
Change sync level or target. Levels: research (articles, findings, entries), mine (conversations, submission status).
JSON body fields: {"repo":"owner/name?","branch":"string?","base_path":"string?","levels":"('research'|'mine')[]?"}

### POST /me/sync/down [reader:write]
Queue a best-effort repo export; returns HTTP 202 with a job receipt. Idempotency-Key supported; priority reserves Arkyve credits.
JSON body fields: {"lane":"free|priority (default free)"}

### POST /me/sync/up [reader:write]
Queue finding files for review; HTTP 202 receipt. Each file version is sent once. Paid priority never promises instant completion.
JSON body fields: {"lane":"free|priority (default free)"}

### GET /jobs/{id} [read]
Job receipt: status, estimate, reservation, deferred reason, result.

### POST /jobs/{id}/cancel [reader:write]
Cancel a queued/deferred job; releases reservations.

### POST /findings [reader:write]
Submit a sourced finding for review. Idempotent by content digest.
JSON body fields: {"publication_id":"string","statement":"string","source_urls":"string[]","entry_ids":"string[] (required, 1-50 entry UUIDs from GET /entries or a synced entries.jsonl; findings must build on collected entries; carried onto the finding on acceptance)","question_ids":"uuid[]? (optional, up to 20 editorial question IDs the finding helps answer; carried onto the finding on acceptance)","evidence":"string?"}

Quick start

Connect GitHub and choose your repo under Your repo & agent, then create a token. Store it as a secret.
GET /capabilities — the operations available to your token, your scopes, global constraints.
GET /publications/language-ledger/context — perspective, evidence standard, taxonomy, permitted actions.
POST /me/sync/down to request an export. Work locally; place sourced findings in your repo and request POST /me/sync/up.

curl -X POST $ORIGIN/api/public/v1/me/sync/down \
  -H "Authorization: Bearer ark_…" -H "content-type: application/json" \
  -H "Idempotency-Key: export-2026-10-21" \
  -d '{"lane":"free"}'

Sync requests return HTTP 202 and a job receipt. Check GET /jobs/{id} for completion or cancel before work starts. Free is best effort; {"lane":"priority"} reserves Arkyve credits. Priority never guarantees instant completion; failed and cancelled requests release credits.

Discovery

GET/capabilitiespublicList operations, scopes and constraints.
GET/openapi.jsonpublicOpenAPI 3.1 contract.
GET/budgetpublicGlobal budget availability (cap, spent, reserved, free-only).
GET/publicationspublicLive publications.
GET/publications/{id}/contextpublicPublication context: purpose, audience, domains, guide persona, evidence standard, taxonomy, article schema, modules, permitted actions.

Publishing

GET/publications/{id}/articlespublicPublished articles.

Research

GET/domainspublicResearch domains.
GET/sourcespublicSources with primary/secondary domains, health, consecutive failure count and last success. Retired sources are hidden unless ?status=retired. Filter ?domain=&status=
GET/entriespublicCollected entries. ?source=&domain=&updated_since=&cursor=&limit=
GET/findingspublicAccepted findings with entry IDs. ?domain=&cursor=

Reader self-service

GET/mereadOwn profile, subscriptions (sensitive context excluded) and credit balance.
GET/me/creditsreadOwn credit ledger.
GET/me/conversationsreadOwn conversations with messages.
GET/me/submissionsreadOwn contribution review status.
GET/publications/{id}/findings-promptreadAgent-ready guidance for distilling entries into domain findings using a live publication's interests as an editorial lens, not publication-owned findings. Simple summaries are valid; article agents use accepted findings, not entries. Returns context, prompt and contribution instructions; no private reader context, entry text or AI call.
POST/findingsreader:writeSubmit a sourced finding for review. Idempotent by content digest.

Repo sync

GET/me/syncreadYour GitHub settings, recent sync job receipts, credit balance and priority cost.
PATCH/me/syncreader:writeChange sync level or target. Levels: research (articles, findings, entries), mine (conversations, submission status).
POST/me/sync/downreader:writeQueue a best-effort repo export; returns HTTP 202 with a job receipt. Idempotency-Key supported; priority reserves Arkyve credits.
POST/me/sync/upreader:writeQueue finding files for review; HTTP 202 receipt. Each file version is sent once. Paid priority never promises instant completion.

Jobs

GET/jobs/{id}readJob receipt: status, estimate, reservation, deferred reason, result.
POST/jobs/{id}/cancelreader:writeCancel a queued/deferred job; releases reservations.