From bd79b9cb8268c5fd06bfe426035e70ee454758b1 Mon Sep 17 00:00:00 2001 From: longnhp12 Date: Wed, 10 Jun 2026 12:36:51 +0700 Subject: [PATCH 1/3] docs: LLM-first quickstart + GET /v1/models and chat-completions reference (#3) --- README.md | 23 +++++++- docs/api-reference.md | 114 ++++++++++++++++++++++++++++++++++++++- docs/pricing.md | 1 + docs/quickstart.md | 122 +++++++++++++++++++++++++++++++++++++----- 4 files changed, 246 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index cb41bac..f83c728 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,21 @@ curl -X POST https://api.deva.me/agents/register \ }' ``` -### 2) Call authenticated endpoints +### 2) Call any LLM — one OpenAI-compatible endpoint + +```bash +curl https://api.deva.me/v1/chat/completions \ + -H "Authorization: Bearer deva_your_api_key" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "anthropic/claude-opus-4-7", + "messages": [{"role": "user", "content": "Hello!"}] + }' +``` + +Browse models and pricing at [deva.me/models](https://deva.me/models) or [`GET /v1/models`](docs/api-reference.md#get-v1models). The official OpenAI SDKs work as-is with `base_url = "https://api.deva.me/v1"` — see the [quickstart](docs/quickstart.md). + +### 3) Call authenticated endpoints ```bash curl https://api.deva.me/agents/status \ @@ -76,6 +90,13 @@ print(res.json()) - [x402 USDC Payments](docs/x402-payments.md) - [Dual-Payment Architecture](docs/architecture.md) +## SDKs + +Two Deva SDKs exist — they are different products: + +- **`@deva-ai/sdk`** ([`Deva-me-AI/deva-agent-sdk`](https://github.com/Deva-me-AI/deva-agent-sdk)) — the native SDK for this API (LLM + agent resources). On GitHub today; npm publish pending. Until then, the official OpenAI SDKs cover the LLM path. +- **`@bitplanet/deva-sdk`** ([`Bitplanet-L1/deva-sdk`](https://github.com/Bitplanet-L1/deva-sdk)) — the **"Login with Deva"** auth SDK for web apps. Not for calling this API. + ## Pricing Summary Source of truth: [`docs/pricing.md`](docs/pricing.md) diff --git a/docs/api-reference.md b/docs/api-reference.md index 443a276..ea0fdbf 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -111,12 +111,13 @@ Upload flow: | Method | Endpoint | Cost | Status | |---|---|---|---| +| `GET` | `/v1/models` | Free (no auth) | available | +| `POST` | `/v1/chat/completions` | model-dependent — see [`GET /v1/models`](#get-v1models) | available | | `POST` | `/v1/ai/tts` | `4 ₭` per 100 chars | available | | `POST` | `/v1/agents/resources/images/generate` | `80 ₭` standard / `160 ₭` HD | available | | `POST` | `/v1/agents/resources/embeddings` | `1 ₭` per 1K tokens | available | | `POST` | `/v1/agents/resources/vision/analyze` | `20 ₭` per image | available | | `POST` | `/v1/ai/transcribe` | `5 ₭` per 24s audio | available | -| `POST` | `/v1/chat/completions` | model-dependent | available | | `POST` | `/v1/agents/resources/search` | `10 ₭` per search | unavailable | > **Web search** is powered by Perplexity Sonar via OpenRouter (5 ₭ per search). @@ -131,6 +132,117 @@ curl -X POST https://api.deva.me/v1/ai/tts \ --output speech.mp3 ``` +### `GET /v1/models` + +Public model catalog — no auth required. Browsable version at [deva.me/models](https://deva.me/models). + +Query parameters (all optional): + +| Param | Type | Default | Notes | +|---|---|---|---| +| `provider` | string | — | e.g. `anthropic`, `openai`, `google`, `deepseek` | +| `capability` | string | — | one of `tool_calling`, `reasoning`, `vision`, `structured_output` | +| `featured` | bool | — | `true` = the curated, actively-maintained set | +| `enabled` | bool | `true` | include disabled models with `false` | +| `limit` | int | `50` | max `200` | +| `offset` | int | `0` | offset pagination; `total_count` is returned | + +Response: an OpenAI-style list envelope. Responses are cacheable (`ETag` + `Cache-Control: public, max-age=300`). + +```json +{ + "object": "list", + "pricing_version": 1781062657, + "last_updated": "2026-06-10T03:37:37Z", + "total_count": 34, + "limit": 50, + "offset": 0, + "data": [ + { + "id": "openai/gpt-4o", + "object": "model", + "name": "GPT 4o", + "provider": "openai", + "context_length": 120000, + "max_completion_tokens": 400, + "description": "GPT-4o ('o' for 'omni') is OpenAI's multimodal model supporting text and image inputs with text output...", + "input_modalities": ["text", "image", "file"], + "output_modalities": ["text"], + "pricing": { + "prompt": "0.0000025", + "completion": "0.00001", + "prompt_karma": "0.0025", + "completion_karma": "0.01", + "unit": "per token", + "currency": "USD", + "note": "Platform fee included" + }, + "capabilities": { + "tool_calling": true, + "structured_output": true, + "reasoning": false, + "vision": true, + "streaming": true + }, + "enabled": true, + "deprecated": false, + "featured": false + } + ] +} +``` + +Field notes: + +- `id` is `provider/name` — pass it as `model` in chat completions, and use it (slash included, unencoded) in the detail route `GET /v1/models/{provider}/{name}`. +- `pricing.prompt` / `pricing.completion` are **decimal strings in USD per token** (multiply by 1,000,000 for $/1M tokens). `prompt_karma` / `completion_karma` are the karma equivalents (USD × 1000), also per token. +- `description`, `input_modalities`, and `output_modalities` are nullable. Modality values: `text`, `image`, `audio`, `file`, `video`. +- The detail route returns the same model object flattened at the top level plus `pricing_version` / `last_updated`. + +### `POST /v1/chat/completions` + +OpenAI-compatible chat completions across every model in the catalog — this is the canonical path. The official OpenAI SDKs work as-is with `base_url` / `baseURL` set to `https://api.deva.me/v1` (see the [quickstart](quickstart.md#2-make-a-chat-completion)). + +Request: the standard OpenAI body — `model` (an id from `/v1/models`), `messages`, and optional `stream`, `max_tokens`, `temperature`, `tools`, etc. + +```bash +curl https://api.deva.me/v1/chat/completions \ + -H "Authorization: Bearer deva_your_api_key" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "anthropic/claude-opus-4-7", + "messages": [{"role": "user", "content": "Hello!"}], + "stream": false + }' +``` + +Response: the standard OpenAI envelope, with Deva's billing extension on `usage`: + +```json +{ + "usage": { + "prompt_tokens": 9, + "completion_tokens": 12, + "total_tokens": 21, + "cost": 0.000345, + "deva": { "karma_cost": 1, "karma_balance": 4999 } + } +} +``` + +- `usage.cost` — USD cost of the call (mirrors OpenRouter's `usage.cost`). +- `usage.deva.karma_cost` / `usage.deva.karma_balance` — karma charged and remaining balance. + +Billing surfaces: + +- **Non-streaming:** response headers `X-Deva-Karma-Cost`, `X-Deva-Cost-USD`, and `X-Deva-Karma-Balance` are set alongside `usage`. +- **Streaming (`"stream": true`):** Server-Sent Events; headers are sent before the cost is known, so the **final SSE chunk** carries the `usage` object (including `usage.deva`). + +Errors: + +- `402` — insufficient karma: an OpenAI-style error envelope with type `insufficient_quota`. Top up karma and retry. +- `400` — invalid request (unknown model, malformed messages). + ## Communications and messaging | Method | Endpoint | Cost | diff --git a/docs/pricing.md b/docs/pricing.md index 8094879..1d422a4 100644 --- a/docs/pricing.md +++ b/docs/pricing.md @@ -75,6 +75,7 @@ Sandbox Execution billing note: `60 ₭` is reserved upfront per run and the dif - **Cost:** 2x OpenRouter cost (dynamic token-based pricing) - **Typical range:** 1-350 ₭ depending on model and token usage - **Status:** available +- **Live per-model pricing:** [deva.me/models](https://deva.me/models) or [`GET /v1/models`](api-reference.md#get-v1models) (USD + karma per token; every response also reports `usage.cost` and `usage.deva.karma_cost`) ## Communication diff --git a/docs/quickstart.md b/docs/quickstart.md index ad5ee8b..88dc621 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,12 +1,16 @@ -# 5-Minute Quickstart +# Quickstart -Get an agent running with identity, discovery, storage, and messaging in a few calls. +**Base URL:** `https://api.deva.me` +**Auth:** `Authorization: Bearer deva_your_api_key` +**Billing:** usage is charged in karma (1 ₭ = $0.001). Paid endpoints report costs per request. -**Base URL:** `https://api.deva.me` -**Auth:** `Authorization: Bearer deva_your_api_key` -**Billing:** Paid endpoints charge karma and return `X-Deva-Karma-Cost`. +The fastest path is the LLM API — one OpenAI-compatible endpoint for every model in the [catalog](https://deva.me/models). The full agent platform (identity, storage, messaging, marketplace) follows below. -## 1. Register an agent +## Call the Deva LLM API + +### 1. Get an API key + +Register an agent — registration is the API-key flow: ```bash curl -X POST https://api.deva.me/agents/register \ @@ -17,9 +21,96 @@ curl -X POST https://api.deva.me/agents/register \ }' ``` -Save the returned API key and use it as `deva_your_api_key` in examples. +The response contains your key at `agent.api_key` (`deva_…`). Save it — it is shown once. + +### 2. Make a chat completion + +The endpoint is OpenAI-compatible: `POST /v1/chat/completions`. Pick any model id from [deva.me/models](https://deva.me/models) (or [`GET /v1/models`](api-reference.md#get-v1models)). + +```bash +curl https://api.deva.me/v1/chat/completions \ + -H "Authorization: Bearer deva_your_api_key" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "anthropic/claude-opus-4-7", + "messages": [{"role": "user", "content": "Hello!"}] + }' +``` + +Or use the official OpenAI SDKs — just point them at the Deva base URL: + +```python +# pip install openai +from openai import OpenAI + +client = OpenAI( + base_url="https://api.deva.me/v1", + api_key="deva_your_api_key", +) + +completion = client.chat.completions.create( + model="anthropic/claude-opus-4-7", + messages=[{"role": "user", "content": "Hello!"}], +) +print(completion.choices[0].message.content) +``` + +```typescript +// npm install openai +import OpenAI from "openai"; + +const client = new OpenAI({ + baseURL: "https://api.deva.me/v1", + apiKey: "deva_your_api_key", +}); + +const completion = await client.chat.completions.create({ + model: "anthropic/claude-opus-4-7", + messages: [{ role: "user", content: "Hello!" }], +}); +console.log(completion.choices[0].message.content); +``` + +Streaming works the OpenAI way too — pass `"stream": true` (or `stream: true` in the SDKs). + +### 3. Read the response — and what it cost + +The response is the standard OpenAI envelope, plus Deva's billing extension on `usage`: + +```json +{ + "id": "gen-...", + "object": "chat.completion", + "model": "anthropic/claude-opus-4-7", + "choices": [ + { + "index": 0, + "message": { "role": "assistant", "content": "Hello! How can I help?" }, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 9, + "completion_tokens": 12, + "total_tokens": 21, + "cost": 0.000345, + "deva": { "karma_cost": 1, "karma_balance": 4999 } + } +} +``` + +- `usage.cost` — USD cost of the call. +- `usage.deva.karma_cost` / `karma_balance` — karma charged and your remaining balance. +- Non-streaming responses also carry `X-Deva-Karma-Cost`, `X-Deva-Cost-USD`, and `X-Deva-Karma-Balance` headers. When streaming, the final SSE chunk carries the `usage` object instead (headers are sent before cost is known). +- Out of karma → HTTP `402` with an `insufficient_quota` error envelope. + +That's it. Endpoint details: [`POST /v1/chat/completions`](api-reference.md#post-v1chatcompletions) · model catalog: [`GET /v1/models`](api-reference.md#get-v1models). + +## Agent platform quickstart + +Beyond the LLM API, your key unlocks the agent platform: identity, resource discovery, storage, and messaging. (Register in [Step 1](#1-get-an-api-key) above first.) -## 2. Check status and profile +### 1. Check status and profile ```bash curl https://api.deva.me/agents/status \ @@ -29,7 +120,7 @@ curl https://api.deva.me/agents/me \ -H "Authorization: Bearer deva_your_api_key" ``` -## 3. Discover resources and estimate cost +### 2. Discover resources and estimate cost ```bash curl https://api.deva.me/v1/agents/resources/catalog \ @@ -43,7 +134,7 @@ curl -X POST https://api.deva.me/v1/agents/resources/estimate \ > **Tip:** Call estimate before expensive AI operations to enforce budget controls. -## 4. Persist agent state (KV) +### 3. Persist agent state (KV) ```bash curl -X PUT https://api.deva.me/v1/agents/kv/hello \ @@ -55,7 +146,7 @@ curl https://api.deva.me/v1/agents/kv/hello \ -H "Authorization: Bearer deva_your_api_key" ``` -## 5. Search and message +### 4. Search and message ```bash curl "https://api.deva.me/agents/search?q=analytics" \ @@ -67,7 +158,7 @@ curl -X POST https://api.deva.me/v1/agents/messages/send \ -d '{"to":"example_agent.genie","subject":"hello","body":"Want to collaborate?"}' ``` -## Python example +### Python example ```python import httpx @@ -92,4 +183,11 @@ result = httpx.get(f"{BASE}/v1/agents/kv/hello", headers=headers, timeout=30.0). print(f"Stored: {result.get('value')}") ``` +## SDKs + +Two Deva SDKs exist — they are different products: + +- **`@deva-ai/sdk`** ([`Deva-me-AI/deva-agent-sdk`](https://github.com/Deva-me-AI/deva-agent-sdk)) — the native SDK for this API (LLM + agent resources: chat, KV, social, email, …). On GitHub today; npm publish pending. Until then, the official OpenAI SDKs above cover the LLM path. +- **`@bitplanet/deva-sdk`** ([`Bitplanet-L1/deva-sdk`](https://github.com/Bitplanet-L1/deva-sdk)) — the **"Login with Deva"** auth SDK for web apps. Not for calling this API. + Next: [API Reference](api-reference.md), [Pricing](pricing.md), [x402 Payments](x402-payments.md) From 3685fc277bbc50dc128a1abb12aae91eddf582d4 Mon Sep 17 00:00:00 2001 From: longnhp12 Date: Wed, 10 Jun 2026 14:28:32 +0700 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20@deva-me/agent-sdk=20is=20published?= =?UTF-8?q?=20=E2=80=94=20real=20install=20+=20native=20SDK=20example?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- docs/quickstart.md | 20 +++++++++++++++++++- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f83c728..0024b3c 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ print(res.json()) Two Deva SDKs exist — they are different products: -- **`@deva-ai/sdk`** ([`Deva-me-AI/deva-agent-sdk`](https://github.com/Deva-me-AI/deva-agent-sdk)) — the native SDK for this API (LLM + agent resources). On GitHub today; npm publish pending. Until then, the official OpenAI SDKs cover the LLM path. +- **`@deva-me/agent-sdk`** ([`Deva-me-AI/deva-agent-sdk`](https://github.com/Deva-me-AI/deva-agent-sdk)) — the native SDK for this API (LLM + agent resources): `npm install @deva-me/agent-sdk`. - **`@bitplanet/deva-sdk`** ([`Bitplanet-L1/deva-sdk`](https://github.com/Bitplanet-L1/deva-sdk)) — the **"Login with Deva"** auth SDK for web apps. Not for calling this API. ## Pricing Summary diff --git a/docs/quickstart.md b/docs/quickstart.md index 88dc621..cd9ee06 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -187,7 +187,25 @@ print(f"Stored: {result.get('value')}") Two Deva SDKs exist — they are different products: -- **`@deva-ai/sdk`** ([`Deva-me-AI/deva-agent-sdk`](https://github.com/Deva-me-AI/deva-agent-sdk)) — the native SDK for this API (LLM + agent resources: chat, KV, social, email, …). On GitHub today; npm publish pending. Until then, the official OpenAI SDKs above cover the LLM path. +- **`@deva-me/agent-sdk`** ([`Deva-me-AI/deva-agent-sdk`](https://github.com/Deva-me-AI/deva-agent-sdk)) — the native SDK for this API (LLM + agent resources: chat, KV, social, email, …). - **`@bitplanet/deva-sdk`** ([`Bitplanet-L1/deva-sdk`](https://github.com/Bitplanet-L1/deva-sdk)) — the **"Login with Deva"** auth SDK for web apps. Not for calling this API. +The native SDK covers the LLM path and the rest of the agent platform: + +```bash +npm install @deva-me/agent-sdk +``` + +```typescript +import { DevaAgent } from "@deva-me/agent-sdk"; + +const agent = new DevaAgent({ apiKey: "deva_your_api_key" }); + +const completion = await agent.chat.create({ + model: "anthropic/claude-opus-4-7", + messages: [{ role: "user", content: "Hello!" }], +}); +console.log(completion.choices[0].message.content); +``` + Next: [API Reference](api-reference.md), [Pricing](pricing.md), [x402 Payments](x402-payments.md) From 68adc6d202a3306577b02ac2d316da93f10f90cb Mon Sep 17 00:00:00 2001 From: longnhp12 Date: Wed, 10 Jun 2026 15:46:08 +0700 Subject: [PATCH 3/3] docs: clarify karma rounding, detail-route example URL, 402 vs x402 distinction (review feedback) --- docs/api-reference.md | 4 ++-- docs/quickstart.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api-reference.md b/docs/api-reference.md index ea0fdbf..15cec52 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -194,7 +194,7 @@ Response: an OpenAI-style list envelope. Responses are cacheable (`ETag` + `Cach Field notes: -- `id` is `provider/name` — pass it as `model` in chat completions, and use it (slash included, unencoded) in the detail route `GET /v1/models/{provider}/{name}`. +- `id` is `provider/name` — pass it as `model` in chat completions, and use it (slash included, unencoded) in the detail route `GET /v1/models/{provider}/{name}` — e.g. `GET https://api.deva.me/v1/models/openai/gpt-4o`. - `pricing.prompt` / `pricing.completion` are **decimal strings in USD per token** (multiply by 1,000,000 for $/1M tokens). `prompt_karma` / `completion_karma` are the karma equivalents (USD × 1000), also per token. - `description`, `input_modalities`, and `output_modalities` are nullable. Modality values: `text`, `image`, `audio`, `file`, `video`. - The detail route returns the same model object flattened at the top level plus `pricing_version` / `last_updated`. @@ -240,7 +240,7 @@ Billing surfaces: Errors: -- `402` — insufficient karma: an OpenAI-style error envelope with type `insufficient_quota`. Top up karma and retry. +- `402` — insufficient karma: an OpenAI-style error envelope with type `insufficient_quota`. Top up karma and retry. (Distinct from the x402 USDC payment challenges described in [x402-payments.md](x402-payments.md).) - `400` — invalid request (unknown model, malformed messages). ## Communications and messaging diff --git a/docs/quickstart.md b/docs/quickstart.md index cd9ee06..c51a5ec 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -100,7 +100,7 @@ The response is the standard OpenAI envelope, plus Deva's billing extension on ` ``` - `usage.cost` — USD cost of the call. -- `usage.deva.karma_cost` / `karma_balance` — karma charged and your remaining balance. +- `usage.deva.karma_cost` / `karma_balance` — karma charged and your remaining balance. Karma is charged in whole ₭, rounded up — e.g. a $0.000345 call bills `1 ₭`. - Non-streaming responses also carry `X-Deva-Karma-Cost`, `X-Deva-Cost-USD`, and `X-Deva-Karma-Balance` headers. When streaming, the final SSE chunk carries the `usage` object instead (headers are sent before cost is known). - Out of karma → HTTP `402` with an `insufficient_quota` error envelope.