> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom APIs

> Expose your own HTTP services through the Locus catalog, MCP discovery, policy, and billing paths.

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`.

<Info>
  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.
</Info>

## 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.

| Traffic control                   |    Default |           Range |
| --------------------------------- | ---------: | --------------: |
| Requests per minute               |        300 |        1–60,000 |
| Concurrent requests               |         20 |         1–1,000 |
| Upstream timeout                  | 30 seconds |   1–120 seconds |
| Failures before the circuit opens |          5 |           2–100 |
| Observation window                | 60 seconds |   1–600 seconds |
| Circuit cooldown                  | 30 seconds | 1–3,600 seconds |

## 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.

<Accordion title="Manual action limits">
  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.
</Accordion>

### 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:

```bash theme={null}
curl -X POST "$LOCUS_API/api/wrapped/credits/custom-inventory/check-stock" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SKU-1042"}'
```

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.

<CardGroup cols={2}>
  <Card title="The catalog" icon="grid-2" href="/locus-pro/catalog">
    Understand enablement, availability, and pricing.
  </Card>

  <Card title="Activity and analytics" icon="chart-line" href="/locus-pro/activity-and-analytics">
    See how custom calls appear in usage evidence.
  </Card>
</CardGroup>