Skip to content

add agent-api.yaml and agent-api.json file #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ta-dam wants to merge 1 commit into
base: main
Choose a base branch
from
+673 −0
Open

add agent-api.yaml and agent-api.json file #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
388 changes: 388 additions & 0 deletions agent-api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,388 @@
{
"openapi": "3.0.3",
"info": {
"title": "DeepL Agent API",
"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",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.deepl.com",
"description": "Production server"
}
],
"tags": [
{
"name": "agent",
"description": "DeepL Agent workflow operations"
}
],
"paths": {
"/v1/unstable/agent/workflows/{workflowId}/trigger": {
"post": {
"summary": "Trigger a workflow",
"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",
"operationId": "trigger_workflow",
"tags": [
"agent"
],
"security": [
{
"auth_header": []
}
],
"parameters": [
{
"name": "workflowId",
"in": "path",
"description": "Unique identifier of the workflow to trigger",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"example": "e1d78ccb-22e0-4a42-90e4-61884cf10af2"
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"workflow_request"
],
"properties": {
"workflow_request": {
"type": "string",
"description": "JSON string containing the workflow input parameters",
"example": "{\"input\": {\"language\": \"American English\"}}"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successfully triggered the workflow",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TriggerWorkflowResponse"
},
"example": {
"task_id": "e634159a-3414-4f66-a5cd-a1d48ff42ce3",
"ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3",
"polling_url": "/v1/unstable/agent/tasks/e634159a-3414-4f66-a5cd-a1d48ff42ce3",
"last_modified_date": "2025-12-04T10:30:00Z"
}
}
}
},
"400": {
"description": "Bad request - invalid workflow_request JSON or missing required fields",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"message": "Invalid JSON in workflow_request field"
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing API key, or account is not configured for agentic API use",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Workflow not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"message": "Workflow with ID 'e1d78ccb-22e0-4a42-90e4-61884cf10af2' not found"
}
}
}
}
}
}
},
"/v1/unstable/agent/tasks/{taskId}": {
"get": {
"summary": "Get task status",
"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",
"operationId": "get_task_status",
"tags": [
"agent"
],
"security": [
{
"auth_header": []
}
],
"parameters": [
{
"name": "taskId",
"in": "path",
"description": "Unique identifier of the task to retrieve",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"example": "e634159a-3414-4f66-a5cd-a1d48ff42ce3"
}
],
"responses": {
"200": {
"description": "Successfully retrieved task status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetTaskResponse"
},
"examples": {
"in_progress": {
"summary": "Task in progress",
"value": {
"status": "InProgress",
"last_modified_date": "2025-12-04T10:30:00Z",
"ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3",
"result": {}
}
},
"completed": {
"summary": "Task completed",
"value": {
"status": "Completed",
"last_modified_date": "2026-02-27T09:57:50.863818+00:00",
"ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3",
"result": {
"screenshot": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8",
"response": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32",
"data": null
},
"result_data": [
{
"artifactId": "9a2856bf-5333-4fd8-9500-3ea267b729b6",
"contentUrl": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8",
"name": "final_screenshot",
"description": "Final browser screenshot",
"schema": null
},
{
"artifactId": "5e381ed3-1642-40f7-b8de-69338fc4698f",
"contentUrl": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjVlMzgxZWQzLTE2NDItNDBmNy1iOGRlLTY5MzM4ZmM0Njk4ZiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.f8bd75650b8112fff05b6bef8eae83d2472db96266b795f36c6820659c1feaf2",
"name": "Vodafone_News_Last_7_Days.md",
"description": "Top 10 news articles about Vodafone from the last 7 days",
"schema": null
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing API key, or account is not configured for agentic API use",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Task not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"message": "Task with ID 'e634159a-3414-4f66-a5cd-a1d48ff42ce3' not found"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"TriggerWorkflowResponse": {
"type": "object",
"required": [
"task_id",
"last_modified_date"
],
"properties": {
"task_id": {
"type": "string",
"description": "Unique identifier for the triggered workflow task",
"example": "e634159a-3414-4f66-a5cd-a1d48ff42ce3"
},
"ui_url": {
"type": "string",
"nullable": true,
"description": "URL to view the task in the agentic system user interface",
"example": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3"
},
"polling_url": {
"type": "string",
"nullable": true,
"description": "Relative URL endpoint to poll for task status updates",
"example": "/v1/unstable/agent/tasks/e634159a-3414-4f66-a5cd-a1d48ff42ce3"
},
"last_modified_date": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the task was last modified (ISO 8601 format)",
"example": "2025-12-04T10:30:00Z"
}
}
},
"GetTaskResponse": {
"type": "object",
"required": [
"status",
"last_modified_date",
"result"
],
"properties": {
"status": {
"$ref": "#/components/schemas/TaskStatus"
},
"last_modified_date": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the task was last modified (ISO 8601 format)",
"example": "2025-12-04T10:35:00Z"
},
"ui_url": {
"type": "string",
"nullable": true,
"description": "URL to view the task in the agentic UI",
"example": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3"
},
"result": {
"type": "object",
"description": "Workflow result containing presigned URLs to retrieve output artifacts. Present in all responses; empty object `{}` while the task is in progress.",
"properties": {
"response": {
"type": "string",
"nullable": true,
"description": "Presigned URL to retrieve the primary workflow result content. Valid for five minutes.",
"example": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32"
},
"screenshot": {
"type": "string",
"nullable": true,
"description": "Presigned URL to retrieve a screenshot artifact from the workflow. Valid for five minutes.",
"example": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8"
},
"data": {
"nullable": true,
"description": "Additional workflow result data. Structure is workflow-specific."
}
}
},
"result_data": {
"type": "array",
"nullable": true,
"description": "List of all artifacts produced by the workflow, with metadata and presigned content URLs.",
"items": {
"$ref": "#/components/schemas/ResultArtifact"
}
}
}
},
"TaskStatus": {
"type": "string",
"description": "Current status of the task",
"enum": [
"Archived",
"InProgress",
"Completed",
"Canceled",
"Error",
"FeedbackNeeded"
],
"example": "Completed"
},
"ResultArtifact": {
"type": "object",
"required": [
"artifactId",
"contentUrl",
"name",
"description"
],
"properties": {
"artifactId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the artifact.",
"example": "9a2856bf-5333-4fd8-9500-3ea267b729b6"
},
"contentUrl": {
"type": "string",
"description": "Presigned URL to retrieve the artifact content. Valid for five minutes.",
"example": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8"
},
"name": {
"type": "string",
"description": "Filename or identifier of the artifact.",
"example": "final_screenshot"
},
"description": {
"type": "string",
"description": "Human-readable description of the artifact.",
"example": "Final browser screenshot"
},
"schema": {
"nullable": true,
"description": "Optional schema describing the artifact's data structure."
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "Human-readable error message",
"example": "Workflow with ID 'e1d78ccb-22e0-4a42-90e4-61884cf10af2' not found"
}
}
}
},
"securitySchemes": {
"auth_header": {
"type": "apiKey",
"description": "Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme. Example: `DeepL-Auth-Key <api-key>`\n",
"name": "Authorization",
"in": "header"
}
}
}
}
Loading