Terminal Management API

This document describes how to use the account-level Terminal Management API, which allows you to manage terminals using your account API key.

API Description


POST https://api.ticos.ai/v1/terminals

Request Headers

Parameter	Required	Description
Content-Type	Yes	Fixed value: `application/json`
Authorization	Yes	Format: `Bearer <account_api_key>`, API key can be obtained from User Menu → API Keys

Request Body

The request body is in JSON format and contains the following fields:


{
  "name": "name_1",
  "identifier": "id_1",
  "model_id": 123,
  "description": "Terminal of model 123"
}

Request Body Fields

Field	Type	Required	Description
`name`	string	Yes	A user-defined name for the terminal
`identifier`	string	Yes	A unique identifier for the terminal
`model_id`	integer	Yes	The model ID associated with this terminal
`description`	string	No	A description for the terminal

Response

Success Response

After a successful call, the service returns JSON with HTTP status code 201 Created:


{
  "name": "name_1",
  "identifier": "id_1",
  "status": "active",
  "model_id": 123,
  "secret": "ts_d2d5495765f1cdecd290b4a2d291b180", // This is the terminal's secret
  "description": "Terminal of model 123"
}

Error Responses

400 Bad Request: Invalid input (e.g., missing required fields, identifier not unique).
```
{
  "detail": "A terminal with this identifier already exists for this model"
}
```
401 Unauthorized: Authentication failed (e.g., invalid account API key).
500 Internal Server Error: Server-side error.

Example Code

cURL


curl -X POST "https://api.ticos.ai/v1/terminals" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <account_api_key>" \
  -d '{
    "name": "name_1",
    "identifier": "id_1",
    "model_id": 123,
    "description": "Terminal of model 123"
  }'

Python


import requests
import json
 
url = "https://api.ticos.ai/v1/terminals"
 
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <account_api_key>"
}
 
data = {
    "name": "name_1",
    "identifier": "id_1",
    "model_id": 123,
    "description": "Terminal of model 123"
}
 
response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()
print(result)

Common Issues

Issue	Solution
Returns 400 Bad Request	Check if all required fields are provided and the identifier is unique
Returns 401 Unauthorized	Check if the API key in the `Authorization` header is correct and if the key has been revoked