Quickstart

Create a scoped organization API key in the dashboard, send it on every request, and call the authenticated route family your key has access to. Endpoint paths, request bodies, and billing behavior are documented per route as they are verified end to end.

Authentication

External requests authenticate with an organization API key. Studio accepts the key on either an X-API-Key header or the standard Authorization: Bearer header. Keep keys server-side; never embed them in client bundles or commit them to source control.

Authenticate a request
# Authorization header
curl https://api.agentecology.com/v1/agents \
  -H "Authorization: Bearer ae_live_YOUR_KEY"

# X-API-Key header (works for either form)
curl https://api.agentecology.com/v1/agents \
  -H "X-API-Key: ae_live_YOUR_KEY"

Replace ae_live_YOUR_KEY with the key value shown once on creation in the dashboard. Send external API requests to the public API host, api.agentecology.com. The dashboard service is separate from the public API surface.

Scope reference

API keys carry one or more scopes. The dashboard create flow uses this same list (Full Access, Read Only, Agent Execution presets are composed from these five identifiers).

A Write scope can change data or invoke agents. A Metered scope spends organization credits per call. The two are independent: search:read and nodes:read are read-only (not write) yet metered, because public knowledge and search reads are billed per request.

nodes:read is for documented knowledge-node responses. The nodes route accepts documented node types such as LivingSystem, Response, Function, Pattern, Article, and BiosemioticSignal, and each type returns only its documented field set.

agents:invokeWriteMetered
Invoke agents. Execute agent calls. Spends credits per call.
agents:list
List agents. Browse the agent directory. Free to call.
nodes:readMetered
Read knowledge nodes. Read approved public graph node types and fields. Reads can spend credits.
search:readMetered
Search. Run semantic and structured search and knowledge lookups. Reads can spend credits.
usage:read
View usage. Read usage and billing metrics. Free to call.

Authenticated route families

Each family is gated by one or more scopes. The first detailed route set is published in the workflow integration reference.

  • AgentsMetered

    agents:list, agents:invoke

    Discover and invoke agents. Invocation spends credits.

  • Jobs

    agents:invoke

    Poll async agent invocations and read terminal results. Requires invocation scope but does not spend credits per poll.

  • SearchMetered

    search:read

    Run semantic and structured search across configured indexes. Reads can spend credits.

  • Knowledge nodesMetered

    nodes:read

    Read documented knowledge node types and fields. Reads can spend credits.

  • Usage

    usage:read

    Read usage and billing metrics for the calling organization. Free.

Next step

Sign in to manage your organization, create a scoped API key with the scopes above, and inspect the dashboard state available to your account.

Sign inWorkflow endpoints