Skip to content

Commit 4471464

Browse files
standujarstandujar
committed
docs: fix
1 parent 8eef00e commit 4471464

3 files changed

Lines changed: 144 additions & 87 deletions

File tree

‎rest-reference/jobs/create-job.mdx‎

Lines changed: 40 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -3,39 +3,32 @@ title: "Create Job"
33
api: "POST /api/messaging/jobs"
44
---
55

6-
Create a one-off messaging job. Jobs are used for fire-and-forget message processing with optional callbacks.
6+
Create a one-off messaging job. Jobs are used for fire-and-forget message processing where the agent processes a prompt and returns a response.
77

88
<Note>
99
This endpoint requires API key authentication via the `X-API-Key` header.
1010
</Note>
1111

1212
## Request Body
1313

14-
<ParamField body="agentId" type="string" required>
15-
The UUID of the agent to process the message
14+
<ParamField body="userId" type="string" required>
15+
UUID of the user sending the message
1616
</ParamField>
1717

18-
<ParamField body="message" type="object" required>
19-
The message to process
20-
<Expandable title="Message object">
21-
<ParamField body="entityId" type="string" required>
22-
UUID of the entity sending the message
23-
</ParamField>
24-
<ParamField body="roomId" type="string" required>
25-
UUID of the room
26-
</ParamField>
27-
<ParamField body="content" type="object" required>
28-
Message content with `text` and `source` fields
29-
</ParamField>
30-
</Expandable>
18+
<ParamField body="content" type="string" required>
19+
The message content/prompt to process (max 50KB)
3120
</ParamField>
3221

33-
<ParamField body="callbackUrl" type="string">
34-
URL to POST results when job completes
22+
<ParamField body="agentId" type="string">
23+
UUID of the agent to process the message. If not provided, uses the first available agent.
3524
</ParamField>
3625

37-
<ParamField body="timeout" type="number" default="30000">
38-
Job timeout in milliseconds
26+
<ParamField body="timeoutMs" type="number" default="120000">
27+
Job timeout in milliseconds (min: 1000, max: 300000)
28+
</ParamField>
29+
30+
<ParamField body="metadata" type="object">
31+
Additional metadata to attach to the job (max 10KB)
3932
</ParamField>
4033

4134
## Response
@@ -45,19 +38,24 @@ This endpoint requires API key authentication via the `X-API-Key` header.
4538
</ResponseField>
4639

4740
<ResponseField name="status" type="string">
48-
Initial job status: `queued`
41+
Initial job status: `pending` or `processing`
4942
</ResponseField>
5043

5144
<ResponseField name="createdAt" type="number">
5245
Unix timestamp of job creation
5346
</ResponseField>
5447

48+
<ResponseField name="expiresAt" type="number">
49+
Unix timestamp when the job will timeout
50+
</ResponseField>
51+
5552
<ResponseExample>
5653
```json
5754
{
58-
"jobId": "job_550e8400-e29b-41d4-a716-446655440001",
59-
"status": "queued",
60-
"createdAt": 1703001234567
55+
"jobId": "550e8400-e29b-41d4-a716-446655440001",
56+
"status": "processing",
57+
"createdAt": 1703001234567,
58+
"expiresAt": 1703001354567
6159
}
6260
```
6361
</ResponseExample>
@@ -69,16 +67,23 @@ curl -X POST https://api.example.com/api/messaging/jobs \
6967
-H "Content-Type: application/json" \
7068
-H "X-API-Key: your-api-key" \
7169
-d '{
72-
"agentId": "550e8400-e29b-41d4-a716-446655440000",
73-
"message": {
74-
"entityId": "user-123",
75-
"roomId": "room-456",
76-
"content": {
77-
"text": "Process this asynchronously",
78-
"source": "api"
79-
}
80-
},
81-
"callbackUrl": "https://your-app.com/webhook",
82-
"timeout": 60000
70+
"userId": "550e8400-e29b-41d4-a716-446655440000",
71+
"content": "Process this asynchronously",
72+
"agentId": "660e8400-e29b-41d4-a716-446655440001",
73+
"timeoutMs": 60000,
74+
"metadata": {
75+
"source": "api",
76+
"priority": "high"
77+
}
8378
}'
8479
```
80+
81+
## Job Status Values
82+
83+
| Status | Description |
84+
|--------|-------------|
85+
| `pending` | Job created, waiting for processing |
86+
| `processing` | Agent is processing the message |
87+
| `completed` | Job finished successfully |
88+
| `failed` | Job failed with an error |
89+
| `timeout` | Job timed out waiting for response |

‎rest-reference/runs/list-agent-runs.mdx‎

Lines changed: 69 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,29 @@ List all execution runs for a specific agent. Runs track the lifecycle of messag
1414
## Query Parameters
1515

1616
<ParamField query="status" type="string">
17-
Filter by run status: `completed`, `failed`, `timeout`, `cancelled`
17+
Filter by run status: `started`, `completed`, `timeout`, `error`, or `all`
1818
</ParamField>
1919

2020
<ParamField query="roomId" type="string">
2121
Filter runs by room ID
2222
</ParamField>
2323

24-
<ParamField query="limit" type="number" default="50">
25-
Maximum number of runs to return (max: 250)
24+
<ParamField query="limit" type="number" default="20">
25+
Maximum number of runs to return (max: 100)
2626
</ParamField>
2727

28-
<ParamField query="before" type="string">
29-
Cursor for pagination - return runs before this ID
28+
<ParamField query="from" type="number">
29+
Return only runs started after this Unix timestamp
30+
</ParamField>
31+
32+
<ParamField query="to" type="number">
33+
Return only runs started before this Unix timestamp
34+
</ParamField>
35+
36+
## Headers
37+
38+
<ParamField header="X-Entity-Id" type="string">
39+
Optional entity ID for Row-Level Security (RLS) filtering
3040
</ParamField>
3141

3242
## Response
@@ -37,45 +47,78 @@ List all execution runs for a specific agent. Runs track the lifecycle of messag
3747
<ResponseField name="runId" type="string">
3848
Unique run identifier
3949
</ResponseField>
40-
<ResponseField name="agentId" type="string">
41-
Agent that executed this run
42-
</ResponseField>
43-
<ResponseField name="roomId" type="string">
44-
Room where the run occurred
50+
<ResponseField name="status" type="string">
51+
Run status: `started`, `completed`, `timeout`, `error`
4552
</ResponseField>
46-
<ResponseField name="startTime" type="number">
53+
<ResponseField name="startedAt" type="number">
4754
Unix timestamp when run started
4855
</ResponseField>
49-
<ResponseField name="endTime" type="number">
50-
Unix timestamp when run ended
56+
<ResponseField name="endedAt" type="number">
57+
Unix timestamp when run ended (null if still running)
5158
</ResponseField>
52-
<ResponseField name="status" type="string">
53-
Run status: `completed`, `failed`, `timeout`, `cancelled`
59+
<ResponseField name="durationMs" type="number">
60+
Duration in milliseconds (null if still running)
5461
</ResponseField>
55-
<ResponseField name="actionsExecuted" type="number">
56-
Number of actions executed
62+
<ResponseField name="messageId" type="string">
63+
ID of the message that triggered this run
5764
</ResponseField>
58-
<ResponseField name="messagesProcessed" type="number">
59-
Number of messages processed
65+
<ResponseField name="roomId" type="string">
66+
Room where the run occurred
67+
</ResponseField>
68+
<ResponseField name="entityId" type="string">
69+
Entity that triggered the run
70+
</ResponseField>
71+
<ResponseField name="counts" type="object">
72+
Aggregated counts for the run
73+
<Expandable title="Counts object">
74+
<ResponseField name="actions" type="number">
75+
Number of actions executed
76+
</ResponseField>
77+
<ResponseField name="modelCalls" type="number">
78+
Number of model API calls made
79+
</ResponseField>
80+
<ResponseField name="errors" type="number">
81+
Number of errors encountered
82+
</ResponseField>
83+
<ResponseField name="evaluators" type="number">
84+
Number of evaluators run
85+
</ResponseField>
86+
</Expandable>
6087
</ResponseField>
6188
</Expandable>
6289
</ResponseField>
6390

91+
<ResponseField name="total" type="number">
92+
Total number of runs matching the filter
93+
</ResponseField>
94+
95+
<ResponseField name="hasMore" type="boolean">
96+
Whether there are more runs available
97+
</ResponseField>
98+
6499
<ResponseExample>
65100
```json
66101
{
67102
"runs": [
68103
{
69104
"runId": "550e8400-e29b-41d4-a716-446655440001",
70-
"agentId": "550e8400-e29b-41d4-a716-446655440000",
71-
"roomId": "660e8400-e29b-41d4-a716-446655440002",
72-
"startTime": 1703001234567,
73-
"endTime": 1703001235890,
74105
"status": "completed",
75-
"actionsExecuted": 2,
76-
"messagesProcessed": 1
106+
"startedAt": 1703001234567,
107+
"endedAt": 1703001235890,
108+
"durationMs": 1323,
109+
"messageId": "770e8400-e29b-41d4-a716-446655440003",
110+
"roomId": "660e8400-e29b-41d4-a716-446655440002",
111+
"entityId": "880e8400-e29b-41d4-a716-446655440004",
112+
"counts": {
113+
"actions": 2,
114+
"modelCalls": 3,
115+
"errors": 0,
116+
"evaluators": 1
117+
}
77118
}
78-
]
119+
],
120+
"total": 42,
121+
"hasMore": true
79122
}
80123
```
81124
</ResponseExample>

‎runtime/types-reference.mdx‎

Lines changed: 35 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -180,8 +180,8 @@ interface ActionPlan {
180180

181181
interface ActionPlanStep {
182182
action: string;
183-
description: string;
184-
status: 'pending' | 'in_progress' | 'completed' | 'failed';
183+
status: 'pending' | 'completed' | 'failed';
184+
error?: string;
185185
result?: ActionResult;
186186
}
187187
```
@@ -208,9 +208,13 @@ Backend-to-frontend control messages:
208208

209209
```typescript
210210
interface ControlMessage {
211-
action: 'disable_input' | 'enable_input';
212-
reason?: string;
213-
metadata?: Record<string, unknown>;
211+
type: 'control';
212+
payload: {
213+
action: 'disable_input' | 'enable_input';
214+
target?: string;
215+
[key: string]: unknown;
216+
};
217+
roomId: UUID;
214218
}
215219
```
216220

@@ -219,15 +223,22 @@ interface ControlMessage {
219223
```typescript
220224
// Emit control message to disable input
221225
await runtime.emit(EventType.CONTROL_MESSAGE, {
222-
action: 'disable_input',
223-
reason: 'Processing your request...'
226+
type: 'control',
227+
payload: {
228+
action: 'disable_input',
229+
},
230+
roomId: currentRoomId
224231
});
225232

226233
// ... do work ...
227234

228235
// Re-enable input
229236
await runtime.emit(EventType.CONTROL_MESSAGE, {
230-
action: 'enable_input'
237+
type: 'control',
238+
payload: {
239+
action: 'enable_input'
240+
},
241+
roomId: currentRoomId
231242
});
232243
```
233244

@@ -239,9 +250,9 @@ Streaming response chunk data:
239250
interface MessageStreamChunkPayload {
240251
messageId: UUID;
241252
chunk: string;
242-
isFirst?: boolean;
243-
isLast?: boolean;
244-
metadata?: Record<string, unknown>;
253+
index: number;
254+
channelId: string;
255+
agentId: UUID;
245256
}
246257
```
247258

@@ -266,14 +277,12 @@ WebSocket message type enum:
266277

267278
```typescript
268279
enum SOCKET_MESSAGE_TYPE {
269-
ROOM_JOINING = 'room:joining',
270-
ROOM_JOINED = 'room:joined',
271-
ROOM_LEFT = 'room:left',
272-
SEND_MESSAGE = 'message:send',
273-
MESSAGE_RECEIVED = 'message:received',
274-
MESSAGE_STREAM = 'message:stream',
275-
CONTROL = 'control',
276-
ERROR = 'error',
280+
ROOM_JOINING = 1,
281+
SEND_MESSAGE = 2,
282+
MESSAGE = 3,
283+
ACK = 4,
284+
THINKING = 5,
285+
CONTROL = 6,
277286
}
278287
```
279288

@@ -462,10 +471,10 @@ Trusted Execution Environment modes:
462471

463472
```typescript
464473
enum TEEMode {
465-
OFF = 'off', // No TEE
466-
LOCAL = 'local', // Local simulation
467-
DOCKER = 'docker', // Docker-based TEE
468-
PRODUCTION = 'production', // Real hardware TEE
474+
OFF = 'OFF', // No TEE
475+
LOCAL = 'LOCAL', // Local simulation
476+
DOCKER = 'DOCKER', // Docker-based TEE
477+
PRODUCTION = 'PRODUCTION', // Real hardware TEE
469478
}
470479
```
471480

@@ -475,12 +484,12 @@ TEE agent registration:
475484

476485
```typescript
477486
interface TeeAgent {
478-
id: UUID;
479-
agentId: UUID;
487+
id: string;
488+
agentId: string;
480489
agentName: string;
481490
createdAt: number;
482491
publicKey: string;
483-
attestation: RemoteAttestationQuote;
492+
attestation: string; // Attestation document as string
484493
}
485494
```
486495

0 commit comments

Comments
 (0)