Neuron Workflows
Neuron

Documentation

Get Started

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

  1. On the canvas, open the neuron's START tab and choose Webhook. The webhook panel opens on its Setup tab.
  2. Under Keys, click New key.
  3. Type a Key name, for example "Production server". Optionally pick a date under Expires (optional).
  4. Click Create key.
  5. Copy the Key id and the Secret now with the copy button next to each. The secret is shown only once. Click Done.

The key is listed under Keys with the end of its ID, when it was last used and its expiry date. Click Revoke to turn it off for good. Until a neuron has a key, its calls are refused ("No keys yet. Calls are rejected until you create one.").

Under Request, the neuron's webhook address is shown after POST. Click Copy to copy it, or Copy curl for a signed example call. See Webhook integration.

Create a key for an agent

  1. Open the agent's setup from My agents and click the Settings tab.
  2. Under When it runs, find From a webhook. The same webhook panel is under it, for this setup.
  3. Create a key under Keys as above, and copy its secret.

A key made here starts only the action it was made for. The From a webhook switch turns the setup's webhook off; calls are then refused.

The API Keys page

Open API keys from the account 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.

  1. On the API Keys page, open the key.
  2. On the Rate Limit card, click Edit.
  3. Enter the most calls allowed and the window in minutes (calls / min).
  4. 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 (its neuron-to-neuron address, under Request in its webhook panel), 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. Each of these calls also carries an X-Neuron-Trace header, and a chain of neurons can go at most 10 hops deep; see Webhook integration.

Results that SEND › API sends to another application don't use an API key. They are signed with a signing secret of their own, shown in the SEND › API panel; see Webhook integration.

The two kinds of key don't swap. An external key can't be used for a call between neurons, and an internal key can't call the address for external applications.

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, that the call goes to the external address under Request, and that it is signed with the key's secret. See Webhook integration.

No API keys found

You haven't created a key yet. Create one in the webhook panel: on a neuron's START › Webhook, or on an agent setup's Settings under From a webhook.

API keys - Docs