Skip to main content
POST
/
v1
/
completions
{
  "messages": [
    {
      "role": "user",
      "content": "What is search volume for keyword 'telefonbox' in Germany?"
    }
  ]
}

{
  "status": true,
  "data": {
    "output": "The search volume for the keyword \"telefonbox\" in Germany is 1,000 searches per month. The global search volume is 1,900. The keyword has a CPC of €8.00 and a low difficulty score of 4.",
    "isCached": false,
    "cacheExpiresIn": null,
    "trace": {
      "steps": [
        {
          "id": "tedi_trace_lxFC14ofn8NolfoX6GAmFlEd",
          "title": "Assess search demand and competition in Germany",
          "networkGroup": "ahrefs",
          "status": "success",
          "icons": [
            "ahrefs"
          ],
          "input": {
            "keywords": "telefonbox",
            "country": "de",
            "select": [
              "keyword",
              "volume",
              "cpc",
              "difficulty",
              "global_volume"
            ],
            "limit": 1000
          },
          "output": [
            {
              "keyword": "telefonbox",
              "volume": 1000,
              "cpc": 800,
              "difficulty": 4,
              "global_volume": 1900
            }
          ],
          "apiData": {
            "provider": "ahrefs",
            "endpoint": "/keywords-explorer/overview",
            "method": "GET",
            "dataSendMethod": "query",
            "url": "https://api.ahrefs.com/v3/keywords-explorer/overview"
          },
          "timestamp": 1760509805563
        }
      ],
      "error": null
    },
    "usage": {
      "promptTokens": 2160,
      "completionTokens": 126,
      "totalTokens": 2286
    }
  }
}
AuthorAuthor: Adnan Ali
Deprecated Endpoint Notice This endpoint is deprecated and will be removed in future versions of the Tedi Agents API.
Tedi completions API allows you to use all tedi features programmatically via a simple REST API. You can integrate Tedi into your applications, services, or workflows to generate AI-powered responses and structured outputs. Entity Reference:
ChatEntity
Examples
File and image processingThe Tedi Completions API does not support file processing via API, such as uploading files or images for analysis. This functionality is currently available only through Dashboard → Chat.At the moment, we do not plan to add this feature to the API, but we’ll continue to monitor demand and may consider it in the future.

​
Completions Types

There are two main types of completions you can use with the Tedi Completions API:
TypeDescription
Text GenerationGenerate human-like text based on prompts
Structured OutputGet responses in predefined JSON formats using JSON-Schema7↗ , Zod-v3↗ and Zod-v4↗ validation
For structured output, you can define a JSON Schema that specifies the expected format of the response. The API will validate the output against this schema and return structured data accordingly.

​
Request

When making a request to the completions endpoint, you can include the following fields in the request body:
​
ChatEntity['messages']
array
required
An array of message objects that define the conversation history.See ChatEntity for detailed configuration options.
​
ChatEntity['output']
object
Optional JSON Schema (Draft 7) that defines the expected structure of the response.See ChatEntity for detailed configuration options.
​
cache
object
An optional object to configure caching behavior for the request.
By default, caching is enabled with a TTL of 120 seconds. You can customize these settings by providing the cache object.

​
Response

​
output
object|string
Tedi completion output. The format of this field depends on whether you provided a JSON Schema in the request:
  • If a JSON Schema was provided, the output will be a structured object conforming to that schema.
  • If no schema was provided, the output will be a plain text string.
​
isCached
boolean
default:false
A boolean indicating whether the response was served from cache.
​
cacheExpiresIn
number
default:120
If the response was served from cache, this field indicates the number of seconds until the cache entry expires. If the response was not cached, this field will be null.
​
trace
object
An object containing detailed information about the steps taken during the completion process, including any API calls made, their inputs and outputs, and any errors encountered.
​
usage
object
An object containing token usage statistics for the request.
{
  "messages": [
    {
      "role": "user",
      "content": "What is search volume for keyword 'telefonbox' in Germany?"
    }
  ]
}

{
  "status": true,
  "data": {
    "output": "The search volume for the keyword \"telefonbox\" in Germany is 1,000 searches per month. The global search volume is 1,900. The keyword has a CPC of €8.00 and a low difficulty score of 4.",
    "isCached": false,
    "cacheExpiresIn": null,
    "trace": {
      "steps": [
        {
          "id": "tedi_trace_lxFC14ofn8NolfoX6GAmFlEd",
          "title": "Assess search demand and competition in Germany",
          "networkGroup": "ahrefs",
          "status": "success",
          "icons": [
            "ahrefs"
          ],
          "input": {
            "keywords": "telefonbox",
            "country": "de",
            "select": [
              "keyword",
              "volume",
              "cpc",
              "difficulty",
              "global_volume"
            ],
            "limit": 1000
          },
          "output": [
            {
              "keyword": "telefonbox",
              "volume": 1000,
              "cpc": 800,
              "difficulty": 4,
              "global_volume": 1900
            }
          ],
          "apiData": {
            "provider": "ahrefs",
            "endpoint": "/keywords-explorer/overview",
            "method": "GET",
            "dataSendMethod": "query",
            "url": "https://api.ahrefs.com/v3/keywords-explorer/overview"
          },
          "timestamp": 1760509805563
        }
      ],
      "error": null
    },
    "usage": {
      "promptTokens": 2160,
      "completionTokens": 126,
      "totalTokens": 2286
    }
  }
}