fix(docs): align localized v2 execution examples · simstudioai/sim@f7c6952 · GitHub
Skip to content

Commit f7c6952

Browse files
TheodoreSpeaksTheodoreSpeaks
committed
fix(docs): align localized v2 execution examples
1 parent 5c9671b commit f7c6952

11 files changed

Lines changed: 192 additions & 240 deletions

File tree

‎apps/docs/content/docs/de/api-reference/authentication.mdx‎

Lines changed: 3 additions & 3 deletions

‎apps/docs/content/docs/de/api-reference/getting-started.mdx‎

Lines changed: 31 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ A workflow must be deployed before it can be executed via the API. Click the **D
5252
curl -X POST https://www.sim.ai/api/v2/workflows/{workflowId}/execute \
5353
-H "Content-Type: application/json" \
5454
-H "X-API-Key: YOUR_API_KEY" \
55-
-d '{"inputs": {}}'
55+
-d '{"input": {}}'
5656
```
5757
</Tab>
5858
<Tab value="TypeScript">
@@ -65,12 +65,12 @@ A workflow must be deployed before it can be executed via the API. Click the **D
6565
'Content-Type': 'application/json',
6666
'X-API-Key': process.env.SIM_API_KEY!,
6767
},
68-
body: JSON.stringify({ inputs: {} }),
68+
body: JSON.stringify({ input: {} }),
6969
}
7070
)
7171

7272
const data = await response.json()
73-
console.log(data.output)
73+
console.log(data.data.output)
7474
```
7575
</Tab>
7676
<Tab value="Python">
@@ -84,11 +84,11 @@ A workflow must be deployed before it can be executed via the API. Click the **D
8484
"Content-Type": "application/json",
8585
"X-API-Key": os.environ["SIM_API_KEY"],
8686
},
87-
json={"inputs": {}},
87+
json={"input": {}},
8888
)
8989

9090
data = response.json()
91-
print(data["output"])
91+
print(data["data"]["output"])
9292
```
9393
</Tab>
9494
</Tabs>
@@ -106,74 +106,60 @@ For long-running workflows, use **asynchronous execution** by passing `async: tr
106106
curl -X POST https://www.sim.ai/api/v2/workflows/{workflowId}/execute \
107107
-H "Content-Type: application/json" \
108108
-H "X-API-Key: YOUR_API_KEY" \
109-
-d '{"inputs": {}, "async": true}'
109+
-d '{"input": {}, "async": true}'
110110
```
111111

112-
This returns immediately with a `jobId` and `statusUrl`:
112+
Keyed callers can optionally provide `X-Run-Id: my-run-123` to choose the run ID. Run IDs cannot be reused; a duplicate returns `409`.
113+
114+
This returns immediately with a `runId` and `statusUrl`:
113115

114116
```json
115117
{
116-
"success": true,
117-
"jobId": "job_abc123",
118-
"statusUrl": "https://www.sim.ai/api/jobs/job_abc123",
119-
"message": "Workflow execution started",
120-
"async": true
118+
"data": {
119+
"runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
120+
"statusUrl": "https://www.sim.ai/api/v2/workflows/{workflowId}/runs/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74"
121+
}
121122
}
122123
```
123124

124-
Poll the [Get Job Status](/api-reference/workflow-runs/getWorkflowRunV2) endpoint until the status is `completed` or `failed`:
125+
Poll the run status endpoint until the status is terminal:
125126

126127
```bash
127-
curl https://www.sim.ai/api/jobs/{jobId} \
128+
curl https://www.sim.ai/api/v2/workflows/{workflowId}/runs/{runId}?includeOutput=true \
128129
-H "X-API-Key: YOUR_API_KEY"
129130
```
130131

131132
<Callout type="info">
132-
Job status transitions follow: `queued` → `processing` → `completed` or `failed`. The `output` field is only present when status is `completed`.
133+
Execution status transitions follow: `queued` → `running` → `completed`, `failed`, `cancelled`, or `paused`. The `data.output` field is populated for completed executions when `includeOutput=true`.
133134
</Callout>
134135

135136
## Response Format
136137

137-
Successful responses include an `output` object with your workflow results and a `limits` object with your current rate limit and usage status:
138+
Successful v2 responses wrap the run resource in `data`:
138139

139140
```json
140141
{
141-
"success": true,
142-
"output": {
143-
"result": "Hello, world!"
144-
},
145-
"limits": {
146-
"workflowExecutionRateLimit": {
147-
"sync": {
148-
"requestsPerMinute": 60,
149-
"maxBurst": 10,
150-
"remaining": 59,
151-
"resetAt": "2025-01-01T00:01:00Z"
152-
},
153-
"async": {
154-
"requestsPerMinute": 30,
155-
"maxBurst": 5,
156-
"remaining": 30,
157-
"resetAt": "2025-01-01T00:01:00Z"
158-
}
159-
},
160-
"usage": {
161-
"currentPeriodCost": 1.25,
162-
"limit": 50.00,
163-
"plan": "pro",
164-
"isExceeded": false
165-
}
142+
"data": {
143+
"runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
144+
"workflowId": "{workflowId}",
145+
"status": "completed",
146+
"output": { "result": "Hello, world!" },
147+
"error": null,
148+
"durationMs": 842
166149
}
167150
}
168151
```
169152

170153
## Error Handling
171154

172-
The API uses standard HTTP status codes. Error responses include a human-readable `error` message:
155+
The API uses standard HTTP status codes. v2 errors include a stable code and human-readable message:
173156

174157
```json
175158
{
176-
"error": "Workflow not found"
159+
"error": {
160+
"code": "NOT_FOUND",
161+
"message": "Workflow not found"
162+
}
177163
}
178164
```
179165

@@ -186,12 +172,12 @@ The API uses standard HTTP status codes. Error responses include a human-readabl
186172
| `429` | Rate limit exceeded | Wait for the duration in the `Retry-After` header |
187173

188174
<Callout type="info">
189-
Use the [Get Usage Limits](/api-reference/billing/getBillingStatus) endpoint to check your current rate limit status and billing usage at any time.
175+
Use [Get Billing Status](/api-reference/billing/getBillingStatus) to inspect current credit and storage usage.
190176
</Callout>
191177

192178
## Rate Limits
193179

194-
Rate limits depend on your subscription plan and apply separately to synchronous and asynchronous executions. Every execution response includes a `limits` object showing your current rate limit status.
180+
Rate limits depend on your subscription plan and apply separately to synchronous and asynchronous executions.
195181

196182
When rate limited, the API returns a `429` response with a `Retry-After` header indicating how many seconds to wait before retrying.
197183

‎apps/docs/content/docs/es/api-reference/authentication.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Pass your API key in the `X-API-Key` header with every request:
4444
curl -X POST https://www.sim.ai/api/v2/workflows/{workflowId}/execute \
4545
-H "Content-Type: application/json" \
4646
-H "X-API-Key: YOUR_API_KEY" \
47-
-d '{"inputs": {}}'
47+
-d '{"input": {}}'
4848
```
4949
</Tab>
5050
<Tab value="TypeScript">
@@ -57,7 +57,7 @@ Pass your API key in the `X-API-Key` header with every request:
5757
'Content-Type': 'application/json',
5858
'X-API-Key': process.env.SIM_API_KEY!,
5959
},
60-
body: JSON.stringify({ inputs: {} }),
60+
body: JSON.stringify({ input: {} }),
6161
}
6262
)
6363
```
@@ -72,7 +72,7 @@ Pass your API key in the `X-API-Key` header with every request:
7272
"Content-Type": "application/json",
7373
"X-API-Key": os.environ["SIM_API_KEY"],
7474
},
75-
json={"inputs": {}},
75+
json={"input": {}},
7676
)
7777
```
7878
</Tab>

‎apps/docs/content/docs/es/api-reference/getting-started.mdx‎

Lines changed: 31 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ A workflow must be deployed before it can be executed via the API. Click the **D
5252
curl -X POST https://www.sim.ai/api/v2/workflows/{workflowId}/execute \
5353
-H "Content-Type: application/json" \
5454
-H "X-API-Key: YOUR_API_KEY" \
55-
-d '{"inputs": {}}'
55+
-d '{"input": {}}'
5656
```
5757
</Tab>
5858
<Tab value="TypeScript">
@@ -65,12 +65,12 @@ A workflow must be deployed before it can be executed via the API. Click the **D
6565
'Content-Type': 'application/json',
6666
'X-API-Key': process.env.SIM_API_KEY!,
6767
},
68-
body: JSON.stringify({ inputs: {} }),
68+
body: JSON.stringify({ input: {} }),
6969
}
7070
)
7171

7272
const data = await response.json()
73-
console.log(data.output)
73+
console.log(data.data.output)
7474
```
7575
</Tab>
7676
<Tab value="Python">
@@ -84,11 +84,11 @@ A workflow must be deployed before it can be executed via the API. Click the **D
8484
"Content-Type": "application/json",
8585
"X-API-Key": os.environ["SIM_API_KEY"],
8686
},
87-
json={"inputs": {}},
87+
json={"input": {}},
8888
)
8989

9090
data = response.json()
91-
print(data["output"])
91+
print(data["data"]["output"])
9292
```
9393
</Tab>
9494
</Tabs>
@@ -106,74 +106,60 @@ For long-running workflows, use **asynchronous execution** by passing `async: tr
106106
curl -X POST https://www.sim.ai/api/v2/workflows/{workflowId}/execute \
107107
-H "Content-Type: application/json" \
108108
-H "X-API-Key: YOUR_API_KEY" \
109-
-d '{"inputs": {}, "async": true}'
109+
-d '{"input": {}, "async": true}'
110110
```
111111

112-
This returns immediately with a `jobId` and `statusUrl`:
112+
Keyed callers can optionally provide `X-Run-Id: my-run-123` to choose the run ID. Run IDs cannot be reused; a duplicate returns `409`.
113+
114+
This returns immediately with a `runId` and `statusUrl`:
113115

114116
```json
115117
{
116-
"success": true,
117-
"jobId": "job_abc123",
118-
"statusUrl": "https://www.sim.ai/api/jobs/job_abc123",
119-
"message": "Workflow execution started",
120-
"async": true
118+
"data": {
119+
"runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
120+
"statusUrl": "https://www.sim.ai/api/v2/workflows/{workflowId}/runs/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74"
121+
}
121122
}
122123
```
123124

124-
Poll the [Get Job Status](/api-reference/workflow-runs/getWorkflowRunV2) endpoint until the status is `completed` or `failed`:
125+
Poll the run status endpoint until the status is terminal:
125126

126127
```bash
127-
curl https://www.sim.ai/api/jobs/{jobId} \
128+
curl https://www.sim.ai/api/v2/workflows/{workflowId}/runs/{runId}?includeOutput=true \
128129
-H "X-API-Key: YOUR_API_KEY"
129130
```
130131

131132
<Callout type="info">
132-
Job status transitions follow: `queued` → `processing` → `completed` or `failed`. The `output` field is only present when status is `completed`.
133+
Execution status transitions follow: `queued` → `running` → `completed`, `failed`, `cancelled`, or `paused`. The `data.output` field is populated for completed executions when `includeOutput=true`.
133134
</Callout>
134135

135136
## Response Format
136137

137-
Successful responses include an `output` object with your workflow results and a `limits` object with your current rate limit and usage status:
138+
Successful v2 responses wrap the run resource in `data`:
138139

139140
```json
140141
{
141-
"success": true,
142-
"output": {
143-
"result": "Hello, world!"
144-
},
145-
"limits": {
146-
"workflowExecutionRateLimit": {
147-
"sync": {
148-
"requestsPerMinute": 60,
149-
"maxBurst": 10,
150-
"remaining": 59,
151-
"resetAt": "2025-01-01T00:01:00Z"
152-
},
153-
"async": {
154-
"requestsPerMinute": 30,
155-
"maxBurst": 5,
156-
"remaining": 30,
157-
"resetAt": "2025-01-01T00:01:00Z"
158-
}
159-
},
160-
"usage": {
161-
"currentPeriodCost": 1.25,
162-
"limit": 50.00,
163-
"plan": "pro",
164-
"isExceeded": false
165-
}
142+
"data": {
143+
"runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
144+
"workflowId": "{workflowId}",
145+
"status": "completed",
146+
"output": { "result": "Hello, world!" },
147+
"error": null,
148+
"durationMs": 842
166149
}
167150
}
168151
```
169152

170153
## Error Handling
171154

172-
The API uses standard HTTP status codes. Error responses include a human-readable `error` message:
155+
The API uses standard HTTP status codes. v2 errors include a stable code and human-readable message:
173156

174157
```json
175158
{
176-
"error": "Workflow not found"
159+
"error": {
160+
"code": "NOT_FOUND",
161+
"message": "Workflow not found"
162+
}
177163
}
178164
```
179165

@@ -186,12 +172,12 @@ The API uses standard HTTP status codes. Error responses include a human-readabl
186172
| `429` | Rate limit exceeded | Wait for the duration in the `Retry-After` header |
187173

188174
<Callout type="info">
189-
Use the [Get Usage Limits](/api-reference/billing/getBillingStatus) endpoint to check your current rate limit status and billing usage at any time.
175+
Use [Get Billing Status](/api-reference/billing/getBillingStatus) to inspect current credit and storage usage.
190176
</Callout>
191177

192178
## Rate Limits
193179

194-
Rate limits depend on your subscription plan and apply separately to synchronous and asynchronous executions. Every execution response includes a `limits` object showing your current rate limit status.
180+
Rate limits depend on your subscription plan and apply separately to synchronous and asynchronous executions.
195181

196182
When rate limited, the API returns a `429` response with a `Retry-After` header indicating how many seconds to wait before retrying.
197183

‎apps/docs/content/docs/fr/api-reference/authentication.mdx‎

Lines changed: 3 additions & 3 deletions

0 commit comments

Comments
 (0)