API keys

Create keys that let your own systems start a neuron or an agent, and track how each key is used.

API keys let your own systems, scripts and other services start a neuron or an agent with an HTTP call. Each key belongs to one neuron or agent, has a secret that signs every call, and can have its own rate limit. See Webhook integration for how to make the call.

Create a key for a neuron

On the canvas, open the neuron's START tab and choose Webhook.
Under API webhook & keys, the neuron's webhook address is shown after POST. Copy it for your system.
Click New key.
Type a Key name, for example "Production server". Optionally pick a date under Expires (optional).
Click Create key.
Copy the Key ID and the Secret (Copy secret) now. The secret is shown only once. Click Done.

The key is listed under the address with its expiry date, or No expiry. Click Revoke key to turn it off for good.

Create a key for an agent

Open the agent in My Agents and click the API Endpoint button.
The Direct API Endpoint dialog shows the agent's Webhook URL and how to call it.
Create a key under API key management at the bottom of the dialog, and copy its secret.

The API Keys page

Open API Keys from the profile menu. It shows every key you have made and how each is used.

The cards at the top show External Keys, Total Calls, Success Rate and Credits for the period you pick: 7d, 30d or 90d.
Calls Over Time shows, for each day of the period, how many calls your keys received: successful ones and failed ones.
Credits Consumed shows, for each day, the credits spent by the runs your keys started. A run counts every neuron it reached, including the neurons after the one the key started, and counts even when the run failed after spending credits.
Export downloads the usage for the period as a CSV file.
Search keys... finds a key by name. Show Active, All or Revoked keys; revoked includes keys past their expiry date.
Show internal adds the keys Neuron creates for calls between your own neurons.

Click a key to see its details: Total calls, Success, Latency (average response time), Credits, and charts of its calls and credits.

Set a rate limit on a key

A rate limit caps how many calls a key may make in a time window. Keys have no rate limit until you set one.

On the API Keys page, open the key.
On the Rate Limit card, click Edit.
Enter the most calls allowed and the window in minutes (calls / min).
Click Save. Click Remove to take the limit off.

A call over the limit is refused with "Rate limit exceeded for this API key". The reply has status 429 (Too Many Requests) and a Retry-After header with the number of seconds until the key's window resets; wait that long before retrying.

Key status

Active: the key works, and its calls are logged and counted.
Expired: the key passed its expiry date and no longer works.
Revoked: you revoked the key. It stops working at once. Create a new key to replace it.

Keys between your own neurons

When a neuron's SEND › API sends its result to another of your neurons' webhook addresses, Neuron creates and manages the key for that call itself. You don't need to set anything up. These keys appear on the API Keys page under Show internal.

Calls and credits

Each call starts a run, and the run uses your credits like any other run: you, the key's owner, pay for it, not the system that called.

To see what each integration or system that calls your neuron costs you, give each one its own key. Open a key on the API Keys page to see its own Credits and chart, or use Export to get every call with its credits.

Common problems

I lost a key's secret

A secret is shown only once. Revoke the key, create a new one, and update every system that used the old one.

Calls are refused

Check that the key is Active, that it belongs to the neuron or agent you are calling, and that the call is signed with its secret. See Webhook integration.

No API keys found

You haven't created a key yet. Create one from a neuron's START › Webhook, or from an agent's API Endpoint dialog.