# REST API

Everything Arkivector does is a JSON-over-HTTP call to the daemon, so any language (or a shell) can use it without an SDK. These pages document every endpoint with `curl`, its request fields and its response. Responses shown were captured from a real daemon.

## Conventions

| | |
| :--- | :--- |
| Base URL | `http://127.0.0.1:8080` (wherever `arkivectord` listens) |
| Request bodies | `Content-Type: application/json`, UTF-8. Unknown fields are rejected (`400 bad_request`), so typos fail loudly |
| Responses | `application/json`; errors are `application/problem+json` ([Errors](https://arkivector.dikshitrj.in/docs/api/errors)) |
| Auth | Off by default. With an [API-key file](https://arkivector.dikshitrj.in/docs/operations/security), send `Authorization: Bearer <key>` |
| Block | Data responses carry `as_of_block` and the `Arkivector-As-Of-Block` header ([Consistency](https://arkivector.dikshitrj.in/docs/api/consistency)) |
| Request id | Send `X-Request-Id` (≤ 64 chars) or get a generated one back; it is echoed in errors |
| Field names | `snake_case`. Keys are lowercase hex; addresses come back in EIP-55 case |
| Limits | Body 32 MiB, `k` ≤ 1000, `offset + k` ≤ 1000, 1000 entities per write, 64 searches per batch |

The examples use:

```bash
export AV=http://127.0.0.1:8080
```

## Endpoints

| Method | Path | Page |
| :--- | :--- | :--- |
| GET | `/healthz`, `/readyz` | [Health and version](https://arkivector.dikshitrj.in/docs/api/health) |
| GET | `/v1/version`, `/v1/sync`, `/metrics` | [Health and version](https://arkivector.dikshitrj.in/docs/api/health) |
| GET, POST | `/v1/collections` | [Collections](https://arkivector.dikshitrj.in/docs/api/collections) |
| GET, DELETE | `/v1/collections/{name}` | [Collections](https://arkivector.dikshitrj.in/docs/api/collections) |
| POST | `/v1/collections:follow` | [Collections](https://arkivector.dikshitrj.in/docs/api/collections) |
| POST | `/v1/collections/{name}/entities` | [Upsert entities](https://arkivector.dikshitrj.in/docs/api/entities-upsert) |
| GET | `/v1/collections/{name}/entities/{ref}` | [Get an entity](https://arkivector.dikshitrj.in/docs/api/entities-get) |
| DELETE | `/v1/collections/{name}/entities/{ref}` | [Delete and extend](https://arkivector.dikshitrj.in/docs/api/entities-delete-extend) |
| POST | `/v1/collections/{name}/entities:delete` | [Delete and extend](https://arkivector.dikshitrj.in/docs/api/entities-delete-extend) |
| POST | `/v1/collections/{name}/entities:extend` | [Delete and extend](https://arkivector.dikshitrj.in/docs/api/entities-delete-extend) |
| POST | `/v1/collections/{name}/entities:prepare` | [Prepare](https://arkivector.dikshitrj.in/docs/api/entities-prepare) |
| POST | `/v1/collections/{name}/entities:submit` | [Submit](https://arkivector.dikshitrj.in/docs/api/entities-submit) |
| POST | `/v1/collections/{name}/search` | [Search](https://arkivector.dikshitrj.in/docs/api/search) |
| POST | `/v1/collections/{name}/search:batch` | [Batch search](https://arkivector.dikshitrj.in/docs/api/search-batch) |
| POST | `/v1/collections/{name}/scroll` | [Scroll](https://arkivector.dikshitrj.in/docs/api/scroll) |
| POST | `/v1/collections/{name}/count` | [Count](https://arkivector.dikshitrj.in/docs/api/count) |
| POST | `/mcp` | [MCP server](https://arkivector.dikshitrj.in/docs/mcp) |
| * | `/qdrant/*` | [Qdrant compatibility](https://arkivector.dikshitrj.in/docs/api/qdrant) |

Shared request pieces: [Filters](https://arkivector.dikshitrj.in/docs/api/filters), [Vectors](https://arkivector.dikshitrj.in/docs/api/vectors), [Consistency](https://arkivector.dikshitrj.in/docs/api/consistency).

## Capabilities

`GET /v1/version` lists what this daemon supports (`capabilities`). Managed writes need a daemon signer (`writes_enabled: true`); writes signed by your own wallet ([prepare](https://arkivector.dikshitrj.in/docs/api/entities-prepare) + [submit](https://arkivector.dikshitrj.in/docs/api/entities-submit)) don't. A feature that is absent returns `501 not_implemented`. The SDKs check capabilities before calling.

## Machine-readable contract

[`spec/openapi.yaml`](https://github.com/DikshitRJ/arkivector/blob/main/spec/openapi.yaml) (OpenAPI 3.1) describes every endpoint and schema; [`spec/error-codes.json`](https://github.com/DikshitRJ/arkivector/blob/main/spec/error-codes.json) lists error codes. You can mock the API without a daemon:

```bash
npx --yes @stoplight/prism-cli@5.12.0 mock -p 4010 spec/openapi.yaml
```

---
Web page: https://arkivector.dikshitrj.in/docs/api · All docs on one page: https://arkivector.dikshitrj.in/docs.md · Whole site: https://arkivector.dikshitrj.in/agents.md