Skip to main content
Custom APIs let an enterprise workspace make its own HTTP services callable through Locus. Each provider gets a custom-{provider} namespace, and each action gets a slug such as custom-inventory/check-stock.
This feature must be enabled for your workspace. Custom APIs use your provider account and credential, so review the provider’s security, data handling, and billing terms before enabling an action.

​
Add a provider

Open Agent tools → Custom APIs and add:
  • A name, stable slug, description, and public HTTPS base URL.
  • Bearer, custom-header, query-parameter, or no authentication.
  • Optional rate, concurrency, timeout, and circuit-breaker limits.
The base URL cannot include credentials, a query string, or a fragment. Locus validates the destination before dispatch and never returns a saved raw credential.

​
Add actions

Create an action manually or import it from an OpenAPI document. An action supports GET, POST, PUT, PATCH, or DELETE with a relative path, JSON input schema, valid example, and optional output schema. New actions start disabled. Review the generated slug, schema, provider cost, end-user markup, and example before enabling them.
Input schemas must describe an object, fit within 64 KiB, and stay within 32 nesting levels. Path placeholders must match required scalar input fields. externalUserId, attribution, and _locus are reserved request controls. Provider creation and import request bodies can be up to 4 MiB; execution calls use the platform’s standard request-size limit.

​
Import OpenAPI

Paste or upload an OpenAPI 3.0 or 3.1 JSON or YAML document. Documents can be up to 1 MiB and declare up to 250 operations; select up to 50 compatible actions for one atomic save. The importer supports JSON-shaped operations and explains why it skips unsupported ones. Review the inferred server URL, authentication, schemas, examples, and warnings before saving. Browser drafts do not retain the source document or credentials.

​
Set pricing

Set the provider cost for each action, then optionally add percentage and flat markup for end users.
  • Platform-pool calls consume no Locus credits because your provider bills the saved credential directly.
  • End-user calls consume the configured provider cost plus markup. The full charge is tenant-owned revenue.
  • Both modes create idempotent receipts, activity, webhook events, and replayable results.

​
Discover and execute

Enabled actions appear in the authenticated catalog and MCP discovery tools. Call the returned slug through MCP or the normal enterprise route:
Admission limits and an open circuit fail before a new upstream dispatch; retry those with the same idempotency key. An upstream timeout happens after dispatch and stores a 504 — a retry with the same key replays that stored failure without contacting the provider again. The provider may have accepted the timed-out request, so before repeating a mutating action under a new key, verify the upstream state or rely on the provider’s own idempotency.

​
Manage access

Listing custom providers requires catalog:write. Creating, changing, or deleting providers and actions requires an owner dashboard session with recent step-up authentication, catalog:write, and credentials:manage. Disabling an action removes it from executable discovery. Deleting a provider removes its actions and credential from future use. Existing activity and receipts remain available under their recorded slugs.

The catalog

Understand enablement, availability, and pricing.

Activity and analytics

See how custom calls appear in usage evidence.