> For the complete documentation index, see [llms.txt](https://docs.textmaddie.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.textmaddie.com/documentation/api-reference.md).

# Agent API

The Agent API is how your systems talk to a Text Maddie agent. Hand it a situation and it decides what to send, reads back its own live configuration, manages tags on a contact, and moves conversations between lines.

{% hint style="info" %}
Every endpoint is scoped to a single agent. The key you present determines which agent you are talking to, so there is no agent ID in any request body.
{% endhint %}

## Base URL

```
https://api.textmaddie.com
```

## Get an API key

Keys are minted per agent from your dashboard, and the secret is shown exactly once.

{% stepper %}
{% step %}

#### Open your agent's settings

Sign in to your dashboard, select the agent you want to integrate with, and open **Settings → API keys**. You need the **config manage** permission on the organization to see this page.
{% endstep %}

{% step %}

#### Mint a key

Click **Create key** and give it a name that says where it will be used, for example `zapier-production`. Names are for you: they appear in the key list and in your audit log.
{% endstep %}

{% step %}

#### Copy the secret now

The full secret is returned once, at creation, and never again. Store it in your secret manager before closing the dialog.

```
tma_live_9f2c...
```

{% hint style="warning" %}
If you lose a secret, you cannot recover it. Revoke the key and mint a new one.
{% endhint %}
{% endstep %}
{% endstepper %}

## Authenticate a request

Send the key as a bearer token on every request.

{% tabs %}
{% tab title="cURL" %}

```bash
curl https://api.textmaddie.com/agent/whoami \
  -H "Authorization: Bearer tma_..."
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

httpx.get(
    "https://api.textmaddie.com/agent/whoami",
    headers={"Authorization": "Bearer tma_..."},
)
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
await fetch('https://api.textmaddie.com/agent/whoami', {
  headers: { Authorization: 'Bearer tma_...' },
})
```

{% endtab %}
{% endtabs %}

Call `GET /agent/whoami` to confirm a key works and see which agent it resolves to.

## Revoking a key

Revoke a key from the same settings page. Revocation takes effect on the next request, and any call presenting a revoked key gets a `403`.

{% hint style="danger" %}
If your organization is deactivated, every key stops resolving immediately. Dashboard reads keep working, but invocations do not.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.textmaddie.com/documentation/api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.