doc(docs): Update documentation for v96.0 unified invoke API#4144
doc(docs): Update documentation for v96.0 unified invoke API#4144mmabrouk merged 3 commits intorelease/v0.96.2from
Conversation
Update all documentation to reflect the v96.0 API changes: - Unified /v0/invoke endpoint replacing /generate, /generate_deployed, /test, /run - New request format with data/references/selector structure - New response format with data.outputs, trace_id, span_id, status - Updated config fetch endpoint from /variants/configs/fetch to /preview/applications/revisions/retrieve - Added changelog entry with full migration guide - Added info boxes explaining the selector key concept
dosubot
bot
added
the
size:XL
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
| application_ref: { | ||
| slug: 'my-app' | ||
| }, | ||
| environment_ref: { | ||
| slug: 'staging', | ||
| version: 1, // Optional: omit to fetch latest | ||
| id: null | ||
| version: 1 // Optional: omit to fetch latest | ||
| }, | ||
| application_ref: { | ||
| slug: 'my-app', | ||
| version: null, | ||
| id: null | ||
| } | ||
| key: 'my-app.revision' |
There was a problem hiding this comment.
🔴 API examples for environment-based retrieval send both application_ref and environment_ref, causing 400 error
The JS/TS and curl examples for fetching config by environment include application_ref alongside environment_ref + key. The API router (api/oss/src/apis/fastapi/applications/router.py:1198-1204) explicitly rejects this combination with a 400 error: "Provide either application refs or environment refs with key, not both." The SDK correctly sends only environment_ref + key for environment lookups (sdk/agenta/sdk/managers/shared.py:423-432), omitting application_ref entirely. Users following these doc examples will get 400 errors.
Affected code in JS/TS example
const requestData = {
application_ref: { // ← should NOT be included
slug: 'my-app'
},
environment_ref: {
slug: 'staging',
version: 1
},
key: 'my-app.revision'
};Should be:
const requestData = {
environment_ref: {
slug: 'staging',
version: 1
},
key: 'my-app.revision'
};Prompt for agents
In the 'Fetching by Environment Reference' section of 02-fetch-prompt-programatically.mdx, both the JS/TS example (around lines 231-238) and the curl example (around lines 255-262) include application_ref alongside environment_ref and key in the request body. The API at api/oss/src/apis/fastapi/applications/router.py:1198-1204 rejects requests that include both application refs and environment refs. Remove the application_ref field from these requests, keeping only environment_ref and key. The same issue also appears in:
- docs/docs/getting-started/02-quick-start.mdx (lines 295-301)
- docs/docs/prompt-engineering/01-quick-start.mdx (lines 183-189)
- docs/docs/prompt-engineering/integrating-prompts/05-github.mdx (lines 213-218)
All of these files need the same fix: remove application_ref when doing environment-based retrieval.
Was this helpful? React with 👍 or 👎 to provide feedback.
| application_ref: { | ||
| slug: 'testprompt' | ||
| }, | ||
| environment_ref: { | ||
| slug: 'production', | ||
| id: null | ||
| slug: 'production' | ||
| }, | ||
| application_ref: { | ||
| slug: 'testprompt', | ||
| id: null | ||
| } | ||
| key: 'testprompt.revision' |
There was a problem hiding this comment.
🔴 Quick-start JS/TS example sends application_ref with environment_ref, causing 400 error
Same issue as in the fetch-prompt docs: the JS/TS API example includes application_ref alongside environment_ref + key, which the API rejects at api/oss/src/apis/fastapi/applications/router.py:1198-1204. Users following this quick-start guide will get a 400 error.
| application_ref: { | |
| slug: 'testprompt' | |
| }, | |
| environment_ref: { | |
| slug: 'production', | |
| id: null | |
| slug: 'production' | |
| }, | |
| application_ref: { | |
| slug: 'testprompt', | |
| id: null | |
| } | |
| key: 'testprompt.revision' | |
| application_ref: { | |
| slug: 'testprompt' | |
| }, | |
| environment_ref: { | |
| slug: 'production' | |
| }, | |
| key: 'testprompt.revision' |
Was this helpful? React with 👍 or 👎 to provide feedback.
| application_ref: { | ||
| slug: 'testprompt' | ||
| }, | ||
| environment_ref: { | ||
| slug: 'production', | ||
| id: null | ||
| slug: 'production' | ||
| }, | ||
| application_ref: { | ||
| slug: 'testprompt', | ||
| id: null | ||
| } | ||
| key: 'testprompt.revision' |
There was a problem hiding this comment.
🔴 Getting-started JS/TS example sends application_ref with environment_ref, causing 400 error
Same issue: the JS/TS API example includes application_ref alongside environment_ref + key, which the API rejects at api/oss/src/apis/fastapi/applications/router.py:1198-1204. Users following this getting-started guide will get a 400 error.
| application_ref: { | |
| slug: 'testprompt' | |
| }, | |
| environment_ref: { | |
| slug: 'production', | |
| id: null | |
| slug: 'production' | |
| }, | |
| application_ref: { | |
| slug: 'testprompt', | |
| id: null | |
| } | |
| key: 'testprompt.revision' | |
| application_ref: { | |
| slug: 'testprompt' | |
| }, | |
| environment_ref: { | |
| slug: 'production' | |
| }, | |
| key: 'testprompt.revision' |
Was this helpful? React with 👍 or 👎 to provide feedback.
| "application_ref": { | ||
| "slug": "your-app-slug", | ||
| "version": null, | ||
| "id": null | ||
| "slug": "your-app-slug" | ||
| }, | ||
| "environment_ref": { | ||
| "slug": "production", | ||
| "version": null, | ||
| "id": null | ||
| } | ||
| "slug": "production" | ||
| }, | ||
| "key": "your-app-slug.revision" | ||
| }' > prompt-config.json |
There was a problem hiding this comment.
🔴 GitHub workflow curl example sends application_ref with environment_ref, causing 400 error
The GitHub Actions workflow example sends both application_ref and environment_ref + key in the curl command. The API at api/oss/src/apis/fastapi/applications/router.py:1198-1204 rejects this combination. CI workflows following this example will fail with a 400 error when trying to fetch the prompt config.
| "application_ref": { | |
| "slug": "your-app-slug", | |
| "version": null, | |
| "id": null | |
| "slug": "your-app-slug" | |
| }, | |
| "environment_ref": { | |
| "slug": "production", | |
| "version": null, | |
| "id": null | |
| } | |
| "slug": "production" | |
| }, | |
| "key": "your-app-slug.revision" | |
| }' > prompt-config.json | |
| "environment_ref": { | |
| "slug": "production" | |
| }, | |
| "key": "your-app-slug.revision" |
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
Summary
/v0/invokeendpoint, replacing the legacy/generate,/generate_deployed,/test, and/runendpoints/api/variants/configs/fetchto/api/preview/applications/revisions/retrieveFiles changed
main.mdx+ detailedunified-invoke-api.mdxmigration guideTest plan
cd docs && npm run build)