Skip to content

Commit b6c0e47

Browse files
ta-damta-dam
committed
add agent-api.yaml and agent-api.json file
1 parent 0f1ce79 commit b6c0e47

2 files changed

Lines changed: 673 additions & 0 deletions

File tree

‎agent-api.json‎

Lines changed: 388 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,388 @@
1+
{
2+
"openapi": "3.0.3",
3+
"info": {
4+
"title": "DeepL Agent API",
5+
"description": "API for triggering and monitoring agentic workflows. These endpoints allow users to trigger workflows with custom inputs and poll for task completion status.\n",
6+
"version": "1.0.0"
7+
},
8+
"servers": [
9+
{
10+
"url": "https://api.deepl.com",
11+
"description": "Production server"
12+
}
13+
],
14+
"tags": [
15+
{
16+
"name": "agent",
17+
"description": "DeepL Agent workflow operations"
18+
}
19+
],
20+
"paths": {
21+
"/v1/unstable/agent/workflows/{workflowId}/trigger": {
22+
"post": {
23+
"summary": "Trigger a workflow",
24+
"description": "Triggers an agentic workflow with the specified ID. The workflow will be executed asynchronously, and a task ID will be returned to poll for status updates.\n",
25+
"operationId": "trigger_workflow",
26+
"tags": [
27+
"agent"
28+
],
29+
"security": [
30+
{
31+
"auth_header": []
32+
}
33+
],
34+
"parameters": [
35+
{
36+
"name": "workflowId",
37+
"in": "path",
38+
"description": "Unique identifier of the workflow to trigger",
39+
"required": true,
40+
"schema": {
41+
"type": "string",
42+
"format": "uuid"
43+
},
44+
"example": "e1d78ccb-22e0-4a42-90e4-61884cf10af2"
45+
}
46+
],
47+
"requestBody": {
48+
"required": true,
49+
"content": {
50+
"multipart/form-data": {
51+
"schema": {
52+
"type": "object",
53+
"required": [
54+
"workflow_request"
55+
],
56+
"properties": {
57+
"workflow_request": {
58+
"type": "string",
59+
"description": "JSON string containing the workflow input parameters",
60+
"example": "{\"input\": {\"language\": \"American English\"}}"
61+
}
62+
}
63+
}
64+
}
65+
}
66+
},
67+
"responses": {
68+
"200": {
69+
"description": "Successfully triggered the workflow",
70+
"content": {
71+
"application/json": {
72+
"schema": {
73+
"$ref": "#/components/schemas/TriggerWorkflowResponse"
74+
},
75+
"example": {
76+
"task_id": "e634159a-3414-4f66-a5cd-a1d48ff42ce3",
77+
"ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3",
78+
"polling_url": "/v1/unstable/agent/tasks/e634159a-3414-4f66-a5cd-a1d48ff42ce3",
79+
"last_modified_date": "2025-12-04T10:30:00Z"
80+
}
81+
}
82+
}
83+
},
84+
"400": {
85+
"description": "Bad request - invalid workflow_request JSON or missing required fields",
86+
"content": {
87+
"application/json": {
88+
"schema": {
89+
"$ref": "#/components/schemas/ErrorResponse"
90+
},
91+
"example": {
92+
"message": "Invalid JSON in workflow_request field"
93+
}
94+
}
95+
}
96+
},
97+
"401": {
98+
"description": "Unauthorized - invalid or missing API key, or account is not configured for agentic API use",
99+
"content": {
100+
"application/json": {
101+
"schema": {
102+
"$ref": "#/components/schemas/ErrorResponse"
103+
}
104+
}
105+
}
106+
},
107+
"404": {
108+
"description": "Workflow not found",
109+
"content": {
110+
"application/json": {
111+
"schema": {
112+
"$ref": "#/components/schemas/ErrorResponse"
113+
},
114+
"example": {
115+
"message": "Workflow with ID 'e1d78ccb-22e0-4a42-90e4-61884cf10af2' not found"
116+
}
117+
}
118+
}
119+
}
120+
}
121+
}
122+
},
123+
"/v1/unstable/agent/tasks/{taskId}": {
124+
"get": {
125+
"summary": "Get task status",
126+
"description": "Retrieves the current status and result of a previously triggered workflow task. Use this endpoint to poll for task completion after triggering a workflow.\n",
127+
"operationId": "get_task_status",
128+
"tags": [
129+
"agent"
130+
],
131+
"security": [
132+
{
133+
"auth_header": []
134+
}
135+
],
136+
"parameters": [
137+
{
138+
"name": "taskId",
139+
"in": "path",
140+
"description": "Unique identifier of the task to retrieve",
141+
"required": true,
142+
"schema": {
143+
"type": "string",
144+
"format": "uuid"
145+
},
146+
"example": "e634159a-3414-4f66-a5cd-a1d48ff42ce3"
147+
}
148+
],
149+
"responses": {
150+
"200": {
151+
"description": "Successfully retrieved task status",
152+
"content": {
153+
"application/json": {
154+
"schema": {
155+
"$ref": "#/components/schemas/GetTaskResponse"
156+
},
157+
"examples": {
158+
"in_progress": {
159+
"summary": "Task in progress",
160+
"value": {
161+
"status": "InProgress",
162+
"last_modified_date": "2025-12-04T10:30:00Z",
163+
"ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3",
164+
"result": {}
165+
}
166+
},
167+
"completed": {
168+
"summary": "Task completed",
169+
"value": {
170+
"status": "Completed",
171+
"last_modified_date": "2026-02-27T09:57:50.863818+00:00",
172+
"ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3",
173+
"result": {
174+
"screenshot": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8",
175+
"response": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32",
176+
"data": null
177+
},
178+
"result_data": [
179+
{
180+
"artifactId": "9a2856bf-5333-4fd8-9500-3ea267b729b6",
181+
"contentUrl": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8",
182+
"name": "final_screenshot",
183+
"description": "Final browser screenshot",
184+
"schema": null
185+
},
186+
{
187+
"artifactId": "5e381ed3-1642-40f7-b8de-69338fc4698f",
188+
"contentUrl": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjVlMzgxZWQzLTE2NDItNDBmNy1iOGRlLTY5MzM4ZmM0Njk4ZiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.f8bd75650b8112fff05b6bef8eae83d2472db96266b795f36c6820659c1feaf2",
189+
"name": "Vodafone_News_Last_7_Days.md",
190+
"description": "Top 10 news articles about Vodafone from the last 7 days",
191+
"schema": null
192+
}
193+
]
194+
}
195+
}
196+
}
197+
}
198+
}
199+
},
200+
"401": {
201+
"description": "Unauthorized - invalid or missing API key, or account is not configured for agentic API use",
202+
"content": {
203+
"application/json": {
204+
"schema": {
205+
"$ref": "#/components/schemas/ErrorResponse"
206+
}
207+
}
208+
}
209+
},
210+
"404": {
211+
"description": "Task not found",
212+
"content": {
213+
"application/json": {
214+
"schema": {
215+
"$ref": "#/components/schemas/ErrorResponse"
216+
},
217+
"example": {
218+
"message": "Task with ID 'e634159a-3414-4f66-a5cd-a1d48ff42ce3' not found"
219+
}
220+
}
221+
}
222+
}
223+
}
224+
}
225+
}
226+
},
227+
"components": {
228+
"schemas": {
229+
"TriggerWorkflowResponse": {
230+
"type": "object",
231+
"required": [
232+
"task_id",
233+
"last_modified_date"
234+
],
235+
"properties": {
236+
"task_id": {
237+
"type": "string",
238+
"description": "Unique identifier for the triggered workflow task",
239+
"example": "e634159a-3414-4f66-a5cd-a1d48ff42ce3"
240+
},
241+
"ui_url": {
242+
"type": "string",
243+
"nullable": true,
244+
"description": "URL to view the task in the agentic system user interface",
245+
"example": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3"
246+
},
247+
"polling_url": {
248+
"type": "string",
249+
"nullable": true,
250+
"description": "Relative URL endpoint to poll for task status updates",
251+
"example": "/v1/unstable/agent/tasks/e634159a-3414-4f66-a5cd-a1d48ff42ce3"
252+
},
253+
"last_modified_date": {
254+
"type": "string",
255+
"format": "date-time",
256+
"description": "Timestamp of when the task was last modified (ISO 8601 format)",
257+
"example": "2025-12-04T10:30:00Z"
258+
}
259+
}
260+
},
261+
"GetTaskResponse": {
262+
"type": "object",
263+
"required": [
264+
"status",
265+
"last_modified_date",
266+
"result"
267+
],
268+
"properties": {
269+
"status": {
270+
"$ref": "#/components/schemas/TaskStatus"
271+
},
272+
"last_modified_date": {
273+
"type": "string",
274+
"format": "date-time",
275+
"description": "Timestamp of when the task was last modified (ISO 8601 format)",
276+
"example": "2025-12-04T10:35:00Z"
277+
},
278+
"ui_url": {
279+
"type": "string",
280+
"nullable": true,
281+
"description": "URL to view the task in the agentic UI",
282+
"example": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3"
283+
},
284+
"result": {
285+
"type": "object",
286+
"description": "Workflow result containing presigned URLs to retrieve output artifacts. Present in all responses; empty object `{}` while the task is in progress.",
287+
"properties": {
288+
"response": {
289+
"type": "string",
290+
"nullable": true,
291+
"description": "Presigned URL to retrieve the primary workflow result content. Valid for five minutes.",
292+
"example": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32"
293+
},
294+
"screenshot": {
295+
"type": "string",
296+
"nullable": true,
297+
"description": "Presigned URL to retrieve a screenshot artifact from the workflow. Valid for five minutes.",
298+
"example": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8"
299+
},
300+
"data": {
301+
"nullable": true,
302+
"description": "Additional workflow result data. Structure is workflow-specific."
303+
}
304+
}
305+
},
306+
"result_data": {
307+
"type": "array",
308+
"nullable": true,
309+
"description": "List of all artifacts produced by the workflow, with metadata and presigned content URLs.",
310+
"items": {
311+
"$ref": "#/components/schemas/ResultArtifact"
312+
}
313+
}
314+
}
315+
},
316+
"TaskStatus": {
317+
"type": "string",
318+
"description": "Current status of the task",
319+
"enum": [
320+
"Archived",
321+
"InProgress",
322+
"Completed",
323+
"Canceled",
324+
"Error",
325+
"FeedbackNeeded"
326+
],
327+
"example": "Completed"
328+
},
329+
"ResultArtifact": {
330+
"type": "object",
331+
"required": [
332+
"artifactId",
333+
"contentUrl",
334+
"name",
335+
"description"
336+
],
337+
"properties": {
338+
"artifactId": {
339+
"type": "string",
340+
"format": "uuid",
341+
"description": "Unique identifier of the artifact.",
342+
"example": "9a2856bf-5333-4fd8-9500-3ea267b729b6"
343+
},
344+
"contentUrl": {
345+
"type": "string",
346+
"description": "Presigned URL to retrieve the artifact content. Valid for five minutes.",
347+
"example": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8"
348+
},
349+
"name": {
350+
"type": "string",
351+
"description": "Filename or identifier of the artifact.",
352+
"example": "final_screenshot"
353+
},
354+
"description": {
355+
"type": "string",
356+
"description": "Human-readable description of the artifact.",
357+
"example": "Final browser screenshot"
358+
},
359+
"schema": {
360+
"nullable": true,
361+
"description": "Optional schema describing the artifact's data structure."
362+
}
363+
}
364+
},
365+
"ErrorResponse": {
366+
"type": "object",
367+
"required": [
368+
"message"
369+
],
370+
"properties": {
371+
"message": {
372+
"type": "string",
373+
"description": "Human-readable error message",
374+
"example": "Workflow with ID 'e1d78ccb-22e0-4a42-90e4-61884cf10af2' not found"
375+
}
376+
}
377+
}
378+
},
379+
"securitySchemes": {
380+
"auth_header": {
381+
"type": "apiKey",
382+
"description": "Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme. Example: `DeepL-Auth-Key <api-key>`\n",
383+
"name": "Authorization",
384+
"in": "header"
385+
}
386+
}
387+
}
388+
}

0 commit comments

Comments
 (0)