Skip to content

Commit 699818b

Browse files
openminddevopenminddev
authored
Rewrite core endpoints docs (#2111)
* Revise and expand API reference docs Expanded and clarified multiple API reference pages: updated pricing copy (rates, memory notes, shipping timelines, and plan features) and harmonized changes across mintlify copies. Significantly enhanced endpoint docs: added base URLs, authentication details (JWT/Clerk for core account endpoints, x-api-key for ElevenLabs, API key query for Google ASR), comprehensive request/response examples, error cases, and usage notes for account & key management, ElevenLabs TTS, and Google ASR (rewritten as a WebSocket streaming API with Python/Node/wscat examples and best practices). Renamed and enriched the LLM chat completions doc with supported providers/models, request/response schemas, examples, and advanced parameters. Overall: large content additions, examples, and consistency fixes across docs/api-reference and mintlify/api-reference. * Resolve merge conflict and update docs Clean up documentation: remove leftover merge conflict markers and an outdated curl example in the LLM endpoints file; update a note link label in the Riva endpoint docs from "GitHub Repo" to "Our GitHub"; and correct multiple pricing entries in the introduction pricing table (several OpenAI, GPT-4.1/4.1-mini/nano, GPT-5 variants, DeepSeek, Gemini, grok, qwen, and llama entries) to their accurate values. * Standardize GitHub link text in docs Update Note blocks in riva and vila_vlm endpoint docs (and their mintlify copies) to use consistent link text 'Our GitHub' instead of 'the Our GitHub' or 'GitHub Repo'. This normalizes wording across the documentation.
1 parent b2198d5 commit 699818b

File tree

16 files changed

+5110
-210
lines changed

16 files changed

+5110
-210
lines changed

‎docs/api-reference/api_pricing.mdx‎

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@ $5 per month
2222

2323
Unlimited API key
2424

25-
Low rate limits (5 requests/ per second)
25+
5 requests / second
26+
27+
Session memory (short-term)
2628

2729
Short-term memory
2830

@@ -34,29 +36,25 @@ $25 per month
3436

3537
Higher rate limits
3638

37-
50 requests/per second
39+
20 requests/per second
3840

3941
priority queue
4042

41-
Long-term memory (available March 2026)
43+
Long-term memory (ships March)
4244

4345
Email Support
4446

4547
App Store publishing
4648

47-
Limited apps can be downloaded every month
48-
4949
15K OMCU
5050
</Card>
5151

5252
<Card title="Pro" icon="coin">
5353
$99 per month
5454

55-
200 requests/per second
56-
57-
Unlimited long-term memory
55+
40 requests/per second
5856

59-
Unlimited app store review
57+
Advanced memory controls (ships June)
6058

6159
Slack/Private support channel
6260

@@ -66,15 +64,13 @@ Slack/Private support channel
6664
<Card title="Enterprise" icon="coin">
6765
$999 per month
6866

69-
Dedicated capacity/GPU pools
67+
100 requests/per second
7068

71-
Custom memory backend
69+
Dedicated capacity / GPU pools (ships later this year)
7270

73-
Private model access (available Q4 2026)
71+
Custom integration support
7472

75-
Unlimited app store review
76-
77-
Slack/Private support channel
73+
Private model access (ships later this year)
7874

7975
1.5M OMCU
8076
</Card>

‎docs/api-reference/endpoints/account_and_key_management.mdx‎

Lines changed: 318 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,326 @@ title: Manage Account and Keys
33
description: "Managing your OpenMind Account and API Keys"
44
---
55

6-
Your OpenMind account and API keys are used for authentication and authorization in your applications. You can manage your account and keys via the [OpenMind portal](https://portal.openmind.org) or directly via an API. The API provides access to the full set of operations (generate, delete, account balance, and key listing):
6+
Your OpenMind account and API keys are used for authentication and authorization in your applications. You can manage your account and keys via the [OpenMind portal](https://portal.openmind.org) or directly via an API. The API provides access to the full set of operations (generate, delete, account balance, and key listing).
7+
8+
**Base URL:** `https://api.openmind.org/api/core`
9+
10+
**Authentication:** All endpoints require a JWT token generated with [Clerk](https://clerk.com/). Include the token in the `Authorization` header as a Bearer token.
11+
12+
## Endpoints Overview
13+
14+
| Method | Endpoint | Description |
15+
|--------|----------|-------------|
16+
| POST | `/api_keys/create` | Create a new API key |
17+
| POST | `/api_keys/delete` | Delete an existing API key |
18+
| GET | `/account/balance` | Get your account balance |
19+
| GET | `/api_keys` | List all API keys |
20+
21+
## Create API Key
22+
23+
Create a new API key for your account. Each plan has a limit on the number of API keys you can create.
24+
25+
**Endpoint:** `POST /api_keys/create`
26+
27+
### Request
28+
29+
```bash
30+
curl -X POST https://api.openmind.org/api/core/api_keys/create \
31+
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
32+
-H "Content-Type: application/json"
33+
```
34+
35+
### Response
36+
37+
**Success (200 OK):**
38+
39+
```json
40+
{
41+
"message": "API key created successfully",
42+
"api_key": "om1_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
43+
"api_key_info": {
44+
"id": "a1b2c3d4e5f6g7h8",
45+
"user_id": "user_2abc123xyz",
46+
"name": "api-key-1738713600000",
47+
"prefix": "om1_live_",
48+
"total_cost": 0,
49+
"deleted": false,
50+
"created_at": "2026-02-04T10:00:00Z",
51+
"updated_at": "2026-02-04T10:00:00Z"
52+
}
53+
}
54+
```
55+
56+
**Error Responses:**
57+
58+
```json
59+
// 401 Unauthorized - Missing or invalid JWT token
60+
{
61+
"error": "User not found"
62+
}
63+
64+
// 403 Forbidden - API key limit reached
65+
{
66+
"error": "API key limit reached. Your starter plan allows up to 5 API keys. Please delete an existing key or upgrade your plan."
67+
}
68+
69+
// 500 Internal Server Error
70+
{
71+
"error": "Failed to create API key"
72+
}
73+
```
74+
75+
<Note>The returned `api_key` is only shown once. Store it securely as you won't be able to retrieve it again.</Note>
76+
77+
## Delete API Key
78+
79+
Mark an API key as deleted and invalidate it. This action cannot be undone.
80+
81+
**Endpoint:** `POST /api_keys/delete`
82+
83+
### Request
84+
85+
```bash
86+
curl -X POST https://api.openmind.org/api/core/api_keys/delete \
87+
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
88+
-H "Content-Type: application/json" \
89+
-d '{
90+
"id": "a1b2c3d4e5f6g7h8"
91+
}'
92+
```
93+
94+
### Request Body
95+
96+
| Field | Type | Required | Description |
97+
|-------|------|----------|-------------|
98+
| `id` | string | Yes | The ID of the API key to delete |
99+
100+
### Response
101+
102+
**Success (200 OK):**
103+
104+
```json
105+
{
106+
"message": "API key deleted successfully"
107+
}
108+
```
109+
110+
**Error Responses:**
111+
112+
```json
113+
// 400 Bad Request - Missing or invalid ID
114+
{
115+
"error": "No data provided or invalid format"
116+
}
117+
118+
{
119+
"error": "API key ID is required"
120+
}
121+
122+
// 401 Unauthorized - Missing or invalid JWT token
123+
{
124+
"error": "User not found"
125+
}
126+
127+
// 404 Not Found - API key doesn't exist or doesn't belong to user
128+
{
129+
"error": "API key not found"
130+
}
131+
132+
// 500 Internal Server Error
133+
{
134+
"error": "Failed to delete API key"
135+
}
136+
```
137+
138+
## Get Account Balance
139+
140+
Retrieve your current OMCU (OpenMind Compute Unit) balance and subscription details.
141+
142+
**Endpoint:** `GET /account/balance`
143+
144+
### Request
145+
146+
```bash
147+
curl -X GET https://api.openmind.org/api/core/account/balance \
148+
-H "Authorization: Bearer YOUR_JWT_TOKEN"
149+
```
150+
151+
### Response
152+
153+
**Success (200 OK):**
154+
155+
```json
156+
{
157+
"plan": "pro",
158+
"omcu_balance": 150000,
159+
"monthly_unused_omcu": 50000,
160+
"monthly_total_omcu": 100000,
161+
"current_period_end": "2026-03-04T10:00:00Z",
162+
"cancel_at_period_end": false
163+
}
164+
```
165+
166+
### Response Fields
167+
168+
| Field | Type | Description |
169+
|-------|------|-------------|
170+
| `plan` | string | Your current subscription plan (e.g., "free", "starter", "pro", "enterprise") |
171+
| `omcu_balance` | integer | Total available OMCU credits (monthly + unused prepaid) |
172+
| `monthly_unused_omcu` | integer | Unused OMCU credits from your monthly subscription allowance |
173+
| `monthly_total_omcu` | integer | Total OMCU credits allocated for the current billing period |
174+
| `current_period_end` | string \| null | ISO 8601 timestamp of when the current billing period ends |
175+
| `cancel_at_period_end` | boolean | Whether the subscription will be cancelled at the end of the current period |
176+
177+
**Error Responses:**
178+
179+
```json
180+
// 401 Unauthorized - Missing or invalid JWT token
181+
{
182+
"error": "User not found"
183+
}
184+
185+
// 404 Not Found - User account not found
186+
{
187+
"error": "User not found"
188+
}
189+
```
190+
191+
<Note>
192+
Note the following about your account balance:
193+
- `omcu_balance` represents your total available credits, including both monthly subscription credits and any prepaid/unused credits from previous periods
194+
- Monthly credits reset at the start of each billing period
195+
- Unused prepaid credits do not expire and carry over between billing periods
196+
</Note>
197+
198+
## List API Keys
199+
200+
Retrieve a list of all active API keys for your account.
201+
202+
**Endpoint:** `GET /api_keys`
203+
204+
### Request
7205

8206
```bash
9-
https://api.openmind.org/api/core
207+
curl -X GET https://api.openmind.org/api/core/api_keys \
208+
-H "Authorization: Bearer YOUR_JWT_TOKEN"
209+
```
210+
211+
### Response
10212

11-
post $core/api_keys/create
12-
post $core/api_keys/delete
13-
get $core/account/balance # get your account balance
14-
get $core/api_keys # list API keys
213+
**Success (200 OK):**
214+
215+
```json
216+
{
217+
"api_keys": [
218+
{
219+
"id": "a1b2c3d4e5f6g7h8",
220+
"user_id": "user_2abc123xyz",
221+
"name": "api-key-1738713600000",
222+
"prefix": "om1_live_",
223+
"total_cost": 12500,
224+
"deleted": false,
225+
"created_at": "2026-01-15T10:00:00Z",
226+
"updated_at": "2026-02-04T10:00:00Z"
227+
},
228+
{
229+
"id": "z9y8x7w6v5u4t3s2",
230+
"user_id": "user_2abc123xyz",
231+
"name": "api-key-1738800000000",
232+
"prefix": "om1_live_",
233+
"total_cost": 8750,
234+
"deleted": false,
235+
"created_at": "2026-02-01T15:30:00Z",
236+
"updated_at": "2026-02-04T10:00:00Z"
237+
}
238+
]
239+
}
15240
```
16241

17-
Note: A JWT token is generated with [Clerk](https://clerk.com/) and is used to authenticate your requests. Ensure you have the necessary permissions to access this endpoint.
242+
### Response Fields
243+
244+
Each API key object contains:
245+
246+
| Field | Type | Description |
247+
|-------|------|-------------|
248+
| `id` | string | Unique identifier for the API key |
249+
| `user_id` | string | The user ID this key belongs to |
250+
| `name` | string | Auto-generated name for the key (format: "api-key-{timestamp}") |
251+
| `prefix` | string | The prefix of the API key ("om1_live_" or "om1_test_") |
252+
| `total_cost` | integer | Total OMCU credits consumed by this API key |
253+
| `deleted` | boolean | Whether the key is deleted (always false in this response) |
254+
| `created_at` | string | ISO 8601 timestamp of key creation |
255+
| `updated_at` | string | ISO 8601 timestamp of last update |
256+
257+
**Error Responses:**
258+
259+
```json
260+
// 401 Unauthorized - Missing or invalid JWT token
261+
{
262+
"error": "User not found"
263+
}
264+
265+
// 500 Internal Server Error
266+
{
267+
"error": "Failed to fetch API keys"
268+
}
269+
```
270+
271+
<Note>
272+
Note the following about the API keys listed:
273+
- Only active (non-deleted) API keys are returned.
274+
- The actual secret portion of the API key is never returned in this endpoint.
275+
- The `hashed_key` field is stored in the database but not exposed in the API response for security.
276+
</Note>
277+
278+
## Authentication
279+
280+
All endpoints require authentication using a JWT token issued by Clerk. Include the token in the Authorization header:
281+
282+
```bash
283+
Authorization: Bearer YOUR_JWT_TOKEN
284+
```
285+
286+
### Getting Your JWT Token
287+
288+
You can obtain your JWT token through:
289+
1. **OpenMind Portal:** Log in at [portal.openmind.org](https://portal.openmind.org) and copy your session token
290+
2. **Clerk SDK:** Use the Clerk client library to authenticate and retrieve the session token programmatically
291+
292+
### Example with Token
293+
294+
```bash
295+
# Set your token as an environment variable
296+
export OPENMIND_JWT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
297+
298+
# Use it in your requests
299+
curl -X GET https://api.openmind.org/api/core/account/balance \
300+
-H "Authorization: Bearer $OPENMIND_JWT_TOKEN"
301+
```
302+
303+
## Error Handling
304+
305+
All endpoints follow consistent error response patterns:
306+
307+
### HTTP Status Codes
308+
309+
| Code | Description |
310+
|------|-------------|
311+
| 200 | Success |
312+
| 400 | Bad Request - Invalid input parameters |
313+
| 401 | Unauthorized - Missing or invalid JWT token |
314+
| 403 | Forbidden - Action not allowed (e.g., rate limit reached) |
315+
| 404 | Not Found - Resource doesn't exist |
316+
| 500 | Internal Server Error - Server-side error |
317+
318+
### Error Response Format
319+
320+
```json
321+
{
322+
"error": "Descriptive error message"
323+
}
324+
```
325+
326+
## Rate Limits
327+
328+
API key operations may be subject to rate limits depending on your subscription plan. If you exceed the rate limit, you'll receive a `429 Too Many Requests` response.

0 commit comments

Comments
 (0)