# agentic-endpoints

> Pay-per-call HTTP utilities for autonomous AI agents. There is no
> signup, no API key and no invoice. Every paid endpoint answers 402
> with a price; you sign a stablecoin payment and retry.

## How to pay

Two options, and the same endpoints accept both:

1. **Per call (x402).** Send the request. You get HTTP 402 with a
   `payment-required` header holding a base64 challenge that names the
   amount, the asset (USDC on Base, chain `eip155:8453`) and the
   recipient. Sign an EIP-3009 authorization and retry with an
   `X-PAYMENT` header. Any x402 client library does this for you.
2. **Prepaid credits.** POST to /credits/buy ($5 buys $6.00) or
   /credits/buy-25 ($25 buys $32.50). You get a token back once, and
   only once. Send it as `X-Credit-Token` on any paid endpoint and the
   list price is debited from your balance with no per-call signature.

### Concurrency

Paid calls issued concurrently from the same wallet are refused a
noticeable fraction of the time. The facilitator will not verify
overlapping authorizations from one payer, and you get an ordinary 402.

A 402 means the payment did NOT happen and you were NOT charged: any
status at or above 400 cancels settlement. Retrying with a fresh
signature is safe and will not double-spend. Issue paid calls
sequentially, or retry on 402 with a short backoff. Prepaid credits
avoid this entirely, since they carry no per-call signature to verify.

## Endpoints

### POST /once-key — $0.001

Atomic idempotency witness — claim an action exactly once, record its result, and replay that result to every later caller

Request:
```json
{
  "namespace": "invoices",
  "action_key": "charge-order-1042",
  "ttl": 86400,
  "lease_ttl": 300
}
```

### POST /scrape — $0.005

Web scraping and text extraction

Request:
```json
{
  "url": "https://example.com",
  "format": "text"
}
```

### POST /pdf-parse — $0.01

PDF text extraction

Request:
```json
{
  "url": "https://example.com/report.pdf"
}
```

### POST /compress — $0.005

Token compression for LLMs

Request:
```json
{
  "text": "Long input text to be compressed before it is sent to a model.",
  "target_tokens": 100,
  "strategy": "extractive"
}
```

### POST /vault/store — $0.02

Store an encrypted item in the vault. The first store claims the namespace and returns a one-time namespace_token.

Request:
```json
{
  "namespace": "agent-secrets",
  "key": "openai-api-key",
  "ciphertext": "base64-of-your-client-side-encrypted-bytes",
  "alg": "AES-GCM",
  "ttl": 604800
}
```

### POST /vault/delete — $0.005

Delete an item from the vault (requires the namespace_token)

Request:
```json
{
  "namespace": "agent-secrets",
  "key": "openai-api-key",
  "namespace_token": "the token returned by your first store"
}
```

### POST /credits/buy — $5.00

Buy $6.00 of prepaid credit for $5.00 (20% bonus). Returns a credit token; send it as X-Credit-Token on any paid endpoint to be debited at list price with no per-call payment signature.

### POST /credits/buy-25 — $25.00

Buy $32.50 of prepaid credit for $25.00 (30% bonus). Returns a credit token; send it as X-Credit-Token on any paid endpoint to be debited at list price with no per-call payment signature.

### POST /meetings/import — $0.004

Import a meeting transcript. visibility "private" stores ciphertext this service cannot read; "queryable" stores plaintext and indexes it for search. The first import claims the namespace and returns a one-time namespace_token.

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "title": "Pricing review",
  "occurred_at": "2026-01-04T15:00:00.000Z",
  "source": "webvtt",
  "visibility": "queryable",
  "transcript": "Alice: we agreed to ship the redesign before the audit...",
  "participants": [
    "Alice",
    "Bob"
  ]
}
```

### POST /meetings/search — $0.006

Full-text search across your queryable meetings. Returns ranked excerpts, and reports how many meetings were private and therefore not searched.

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first import",
  "query": "pricing",
  "limit": 10
}
```

### POST /meetings/get — $0.002

Fetch one meeting in full, by meeting_id (requires the namespace_token)

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first import",
  "meeting_id": "6f1c3b90-0f6a-4c2e-9a1e-2b7d5c8e4a11"
}
```

### POST /meetings/list — $0.001

List the meetings in a namespace with their metadata, newest first. Never returns transcripts (requires the namespace_token)

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first import"
}
```

### POST /meetings/delete — $0.001

Delete a meeting and remove it from the search index (requires the namespace_token)

Request:
```json
{
  "namespace": "my-meetings-4f9c2b1e8d7a",
  "namespace_token": "the token returned by your first import",
  "meeting_id": "6f1c3b90-0f6a-4c2e-9a1e-2b7d5c8e4a11"
}
```

### POST /vault/list — $0.001

List the keys held in a vault namespace with their metadata, without returning any ciphertext (requires the namespace_token)

Request:
```json
{
  "namespace": "agent-secrets",
  "namespace_token": "the token returned by your first store"
}
```

### POST /vault/exists — $0.001

Check whether a key exists in the vault without returning its ciphertext (requires the namespace_token)

Request:
```json
{
  "namespace": "agent-secrets",
  "key": "openai-api-key",
  "namespace_token": "the token returned by your first store"
}
```

### POST /vault/retrieve — $0.02

Retrieve an encrypted item from the vault (requires the namespace_token issued at claim time)

Request:
```json
{
  "namespace": "agent-secrets",
  "key": "openai-api-key",
  "namespace_token": "the token returned by your first store"
}
```

## Exactly-once workflow

`/once-key` is the endpoint you cannot replace with a library,
because it answers a question no single agent can answer alone:
has anyone, anywhere, already done this? Use it like this:

1. `POST /once-key` with your `action_key` and a `lease_ttl`.
   - `claimed` — you won. Do the work.
   - `in_progress` — someone else is doing it. Wait
     `retry_after` seconds; do not start the work.
   - `duplicate` — already done. The `result` field holds the
     original outcome; use it and do not repeat the work.
     `has_result` is false if no result was ever recorded, so
     a null result is never mistaken for a lost one. If
     `result_error` is present the stored result could not be
     read back: the work DID run, so do not repeat it, but the
     recorded outcome is lost.
   - `held` — someone else claimed it but has not finished and
     set no lease. There is no result and may never be one. Do
     NOT treat this as done and do NOT do the work; the key is
     locked until `expires_at`.
   - `conflict` — same key, different payload hash. Your key
     derivation is wrong; do not proceed.
2. `POST /once-key/complete` with the `result`. Free. This is
   what lets every later caller learn the outcome.
3. If the work failed, `POST /once-key/release`. Free. The key
   becomes immediately retryable.

If you pass `lease_ttl` and then crash, the claim is released
automatically once the lease lapses and the next caller takes
it over with `recovered: true`. Without `lease_ttl` a claim is
held until its full `ttl`, which is the safer default: nothing
can ever run your side effect twice.

## Free endpoints

- `GET https://ai.oliverkiss.com/` — this catalogue as JSON
- `GET https://ai.oliverkiss.com/health` — liveness
- `GET https://ai.oliverkiss.com/stats` — usage counts, published openly so you
  can tell a maintained service from an abandoned one
- `GET https://ai.oliverkiss.com/status` — uptime, error rate and latency, derived from this service's own cron ticks and request log, so you can judge
  whether it is safe to route paid work through
- `GET https://ai.oliverkiss.com/openapi.json` — OpenAPI 3.1 description
- `POST https://ai.oliverkiss.com/once-key/complete` — Record the outcome of a claimed action_key
- `POST https://ai.oliverkiss.com/vault/rotate-token` — Replace a vault namespace token
- `POST https://ai.oliverkiss.com/once-key/release` — Surrender a claim whose work failed
- `POST https://ai.oliverkiss.com/credits/balance` — Check a prepaid credit balance
- `https://ai.oliverkiss.com/mcp` — Model Context Protocol server (JSON-RPC)