canonical: https://jentic.com/apis/toky.co/toky

# Toky API

Cloud phone system API for managing agents, contacts, calls, SMS, voicemail, webhooks, IVR and phone numbers. The API exposes 36 endpoints secured with apiKey authentication.

## For AI agents

Programmatically list agents, add extra data to agents. Covers 36 operations with apiKey authentication.

## Scope

Does not handle payments, crm, or developer tools - use for communications only.

## Capabilities

- List agents
- Add extra data to agents
- Create new agent
- Update agent group
- Delete agent group

## Use cases

### Communications Operations

Use the Toky API to perform communications operations programmatically. The API provides 36 endpoints covering core functionality including list agents, add extra data to agents, create new agent.

Example prompt: Call GET /agents to list agents

### Automated Agent Management

Automate agent operations by combining multiple Toky API endpoints. Agents can add extra data to agents and then create new agent in a single workflow.

Example prompt: Call POST `/agents/extra_data` to add extra data to agents, then verify the result

### AI Agent Integration via Jentic

AI agents discover and call Toky API endpoints through Jentic without managing credentials directly. An agent searches for the required operation by intent, receives the matching endpoint schema, and executes the call with Jentic-managed authentication. This eliminates the need to read API documentation or handle apiKey tokens manually.

Example prompt: Search Jentic for 'list agents', load the operation schema, and execute with Jentic-managed credentials

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/agents` | List agents |
| POST | `/agents/extra_data` | Add extra data to agents |
| POST | `/agent/create` | Create new agent |
| GET | `/agents_groups` | List agent groups |
| POST | `/agents/groups` | Create agent group |
| PUT | `/agents/groups/{id}` | Update agent group |
| DELETE | `/agents/groups/{id}` | Delete agent group |
| GET | `/cdrs` | List call data records |

## Key resources

- **Agent** — Operations for agent
- **Agents** — Operations for agents
- **Agents_Groups** — Operations for agents_groups
- **Available_Numbers** — Operations for available_numbers
- **Cdrs** — Operations for cdrs

## Why Jentic

- **Setup:** Wiring Toky by hand means setting up its X-Toky-Key header auth, tracking the v1 host, and coding your own retry and pagination handling for agent and call-record listings. Through Jentic you install once, import the Toky API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Toky puts the agent group id in the URL path (`/agents/groups/{id}`), so a rule can pin your agent to one agent group and the operations it needs there. You choose which operations it may call, so destructive ones like deleting an agent group are not included unless you add them.
- **Credential handling:** Your Toky API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list agents' or 'fetch call detail records', and Jentic returns the matching Toky operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Twilio** — Alternative communications API
- **Sendgrid** — Alternative communications API
- **Pusher** — Complementary communications API

## FAQ

### What authentication does the Toky API use?

The Toky API uses an API key passed in the `X-Toky-Key` header. Through Jentic, these credentials are stored encrypted in your Jentic One instance and injected at execution time, so raw secrets never enter the agent context.

### Can I list agents with the Toky API?

Yes. Use the GET /agents endpoint. The API returns structured JSON responses that agents can parse and act on directly.

### What are the rate limits for the Toky API?

Rate limits are not specified in the OpenAPI spec. Check the vendor documentation for current limits. Through Jentic, rate limiting is handled automatically with retry logic built into the execution layer.

### How do I list agents through Jentic?

Install the Jentic SDK with pip install jentic, authenticate through Jentic One, the self-hosted execution layer, then search for 'list agents'. Jentic returns the matching Toky API operation with its input schema. Load the schema and execute the call - credentials are injected automatically.

### How many endpoints does the Toky API have?

The Toky API exposes 36 endpoints covering agent, agents, agents_groups operations.

### Can I limit what my agent is allowed to do with the Toky API?

Yes. Because you run Jentic One yourself and set its rules, you decide which Toky operations the agent may call and which credentials it uses. Toky carries the agent group id in the URL path (`/agents/groups/{id}`), so you can pin the agent to a single agent group and only the calls it needs there, such as listing agents or fetching call data records. Destructive operations like DELETE `/agents/groups/{id}` stay out of scope unless you explicitly grant them.