curl --request POST \
--url https://api.retriever.run/v1/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Trouve 30 fintechs françaises de 50 à 200 salariés avec leur CEO."
}
'{
"id": "run_001",
"workspace_id": "ws_001",
"conversation_id": "conv_001",
"status": "completed",
"message": "J'ai créé la table Fintechs FR avec 30 entreprises.",
"artifacts": [
{
"type": "table",
"id": "tbl_001",
"name": "Fintechs FR",
"effect": "created",
"links": {
"self": "/v1/tables/tbl_001",
"rows": "/v1/tables/tbl_001/rows"
}
}
],
"output": null,
"error": null,
"cancellation_requested": false,
"links": {
"self": "/v1/runs/run_001",
"app": "https://app.retriever.so/app/workspaces/ws_001/conversations/conv_001"
}
}{
"error": {
"code": "invalid_request",
"message": "prompt: prompt must not be blank",
"details": [
{
"path": "prompt",
"message": "prompt must not be blank"
}
]
}
}{
"error": {
"code": "not_authenticated",
"message": "A valid API key is required."
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "conversation_busy",
"message": "This conversation already has an active run."
}
}{
"error": {
"code": "invalid_request",
"message": "Content-Type must be application/json."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded. Retry later."
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}Lancer un run
Enregistre le run et répond immédiatement 202. Suivez-le avec
GET /v1/runs/{id}. Sans workspace_id ni conversation_id,
Retriever crée un workspace et une conversation.
Envoyez un Idempotency-Key pour pouvoir rejouer la requête sans
créer de doublon : même clé + même corps = même run ; même clé +
corps différent = 409 idempotency_conflict.
curl --request POST \
--url https://api.retriever.run/v1/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Trouve 30 fintechs françaises de 50 à 200 salariés avec leur CEO."
}
'{
"id": "run_001",
"workspace_id": "ws_001",
"conversation_id": "conv_001",
"status": "completed",
"message": "J'ai créé la table Fintechs FR avec 30 entreprises.",
"artifacts": [
{
"type": "table",
"id": "tbl_001",
"name": "Fintechs FR",
"effect": "created",
"links": {
"self": "/v1/tables/tbl_001",
"rows": "/v1/tables/tbl_001/rows"
}
}
],
"output": null,
"error": null,
"cancellation_requested": false,
"links": {
"self": "/v1/runs/run_001",
"app": "https://app.retriever.so/app/workspaces/ws_001/conversations/conv_001"
}
}{
"error": {
"code": "invalid_request",
"message": "prompt: prompt must not be blank",
"details": [
{
"path": "prompt",
"message": "prompt must not be blank"
}
]
}
}{
"error": {
"code": "not_authenticated",
"message": "A valid API key is required."
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "conversation_busy",
"message": "This conversation already has an active run."
}
}{
"error": {
"code": "invalid_request",
"message": "Content-Type must be application/json."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded. Retry later."
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}Authorizations
Clé API ret_live_… créée dans Settings → API keys.
Headers
Identifiant unique de la demande côté client (ex. UUID). Non vide.
1Body
Consigne en langage naturel. Non vide.
1Workspace existant. Sinon un workspace est créé.
Continue une conversation (nouveau run dans le même fil).
Contrat de sortie optionnel. Sans lui, le run renvoie message,
artifacts et output: null.
- Option 1
- Option 2
Show child attributes
Show child attributes
Response
Run accepté.
queued, running, recovering, completed, failed, cancelled Texte final de l'agent.
Tables créées ou modifiées par le run (état vivant).
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes