guidesCustom Integrations

Guide: Custom Integrations

When the service you need isn’t one of Chief’s first-class integrations, wire it up through the credential vault.

When to Use This

Use a custom integration if:

  • Your internal API isn’t on the first-class list
  • You want Chief to hit a niche third-party tool
  • You’re prototyping access to a new service before requesting a first-class integration

Setup

Dashboard → Integrations → Add Custom.

You’ll need:

  • Name — what Chief should call it (e.g., “Internal Orders API”)
  • Base URL — https://api.example.com/v1
  • Auth method — API Key, Bearer Token, Basic Auth, or OAuth 2.0
  • Credential — the actual secret value
  • Optional: OpenAPI spec — if your service has one, upload it; Chief learns the endpoints automatically

With OpenAPI

If you uploaded an OpenAPI spec, Chief can call any endpoint by name.

Chief, call our Internal Orders API: GET /orders for the last
24 hours. Group by status and post a count in #ops.

Chief reads the spec, generates the right HTTP request, parses the response, and acts.

Without OpenAPI

Without a spec, you describe the call in plain English:

Chief, hit our Internal Orders API. The endpoint is
GET /orders?since=ISO8601, returns JSON with an array of
order objects. Pull yesterday's data and tell me the total
revenue.

Chief constructs the request, makes it, and reports.

OAuth 2.0 Flows

For OAuth services, the dashboard walks you through:

  1. Authorization URL (where to redirect for consent)
  2. Token URL (where Chief exchanges the code for a token)
  3. Scopes
  4. Refresh handling

Chief stores both access and refresh tokens encrypted, and refreshes automatically when access tokens expire.

Per-Integration Skills

Once a custom integration exists, you can teach Chief reusable workflows on top of it.

Chief, save this as a skill called "ship-order":
1. Look up the order in our Internal Orders API.
2. Check inventory in our WMS API.
3. If both are good, mark order as shipped via PATCH /orders/{id}.
4. Post a confirmation in #ops with the tracking number.

Now anyone in your tenant can say “Chief, ship-order #1234” and the workflow runs.

Approval Wrapping

For destructive or money-moving custom calls, wrap them in an approval.

Chief, set a rule: any DELETE call to our Internal Orders API
needs my approval first.

Pitfalls

  • Rate limits. Chief retries with backoff but won’t burn through your rate limits aggressively. If you hit them, Chief slows down.
  • Auth errors. Tokens expire. Chief reports auth failures clearly and links to the integration card to fix.
  • Spec drift. If you upload an OpenAPI spec and the API changes, re-upload. Otherwise Chief calls the old shape and gets 4xx errors.
  • Internal-only services. If your API is on a private VPC, Chief (running on the public internet) can’t reach it. Use a public ingress with auth, or talk to support about Enterprise on-prem options.
Content CreationData Analysis