Skip to main content
POST
/
api
/
agents
cURL
curl --request POST \
  --url https://app.cotool.ai/api/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "description": "<string>",
  "systemPrompt": "<string>",
  "toolNames": [
    "<string>"
  ],
  "inputs": [
    {
      "type": "text",
      "name": "<string>",
      "description": "<string>",
      "required": true
    }
  ],
  "modelAlias": "<any>",
  "contextDocs": [
    {
      "provider": "googleDocs",
      "id": "<string>",
      "name": "<string>",
      "mimeType": "<string>"
    }
  ],
  "tinesStoryImportId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "planningMode": "never"
}'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "description": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>",
  "toolNames": [
    "<string>"
  ],
  "inputs": [
    {
      "type": "text",
      "name": "<string>",
      "description": "<string>",
      "required": true
    }
  ],
  "modelAlias": "<any>",
  "contextDocs": [
    {
      "provider": "googleDocs",
      "id": "<string>",
      "name": "<string>",
      "mimeType": "<string>"
    }
  ],
  "tinesStoryImportId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "triggerSummary": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "source": "jira",
      "name": "<string>",
      "enabled": true
    }
  ],
  "planningMode": "never"
}

Authorizations

Authorization
string
header
required

API Key authentication for programmatic access. Include your API key in the Authorization header as: Bearer your_api_key_here

Body

application/json

Request body for creating a new AI agent with configuration

name
string
required

Name of the agent

description
string
required

Description of what the agent does

systemPrompt
string
required

System prompt that defines the agent behavior and instructions

toolNames
string[]
required

Array of tool names that this agent can use

inputs
object[]
required

Input configuration defining what inputs the agent expects

modelAlias
any
required

Model alias must be a valid model from the registry

contextDocs
object[]

Optional context documents to provide to the agent

tinesStoryImportId
string<uuid> | null

Optional reference to the Tines story import template used to create this agent

planningMode
enum<string>

Optional planning behavior; defaults to never

Available options:
never,
always,
auto

Response

200 - application/json

Successful response

The newly created agent with generated ID and timestamps

id
string<uuid>
required

Unique identifier for the agent

organizationId
string<uuid>
required

Organization this agent belongs to

name
string
required

Name of the agent

description
string
required

Description of what the agent does

createdAt
string
required

When the agent was created

updatedAt
string
required

When the agent was last updated

deletedAt
string | null
required

When the agent was deleted, if applicable

toolNames
string[]
required

Names of tools available to this agent

inputs
object[]
required

DEPRECATED Input configuration for the agent. This field is no longer used and will be removed in a future version.

modelAlias
any
required

Model alias used by this agent

contextDocs
object[]

Optional context documents

tinesStoryImportId
string<uuid> | null

Reference to the Tines story import template used to create this agent

triggerSummary
object[]

Summary of triggers configured for this agent

planningMode
enum<string>

Planning behavior for this agent

Available options:
never,
always,
auto