Using the API

Amdahl exposes the same workspace operations two ways. Use MCP for agent clients like Claude and Cursor; use the REST API for scripts, automation, and backend services. Both authenticate with the same kind of API key, sent the same way.

Get an API key

In the Amdahl app, open Settings, then Developer and create an API key. The dialog asks for a name, a Permissions level (a named bundle — Read only or Customer agent, plus two admin-only tiers — rather than free-form scopes), and an expiration. The key looks like amdhl_.... You see the full key once, so copy it somewhere safe. Treat it like a password. Anyone with the key can act as you.

Send it on every request

Put the key in an X-API-Key header (an Authorization: Bearer header works just as well — one key, both transports). The REST surface lives under https://app.amdahl.ai/api/platform/v1. Here is a request that proves the key works and hands back something you will use immediately — the catalog of fields you can filter on:

curl https://app.amdahl.ai/api/platform/v1/search/fields \
  -H "X-API-Key: amdhl_your_key_here"

You get one entry per surface (interactions, deals, deal_qualification), each field with its type and the comparison operators it admits — trimmed here to a single field:

{
  "data": {
    "surfaces": [
      {
        "surface": "deals",
        "fields": [
          {
            "name": "deal_amount",
            "type": "FLOAT",
            "description": "The CRM's amount field ...",
            "operators": [
              "eq",
              "neq",
              "in",
              "not_in",
              "gt",
              "gte",
              "lt",
              "lte",
              "between",
              "is_null",
              "not_null"
            ]
          }
        ]
      }
    ]
  }
}

Two things this shows beyond "the key works". Every successful JSON response is wrapped in that data envelope, so the field you want is always one level in — .data.surfaces, not .surfaces. And search.fields needs only data:read, so this call succeeds on any key you can mint, including a Read only one.

See what your key can do

The public surface is documented in two places that never drift from the server:

• The tool catalog — every externally reachable operation with its description, required scopes, and required role.
• The OpenAPI spec — the machine-readable request/response schemas, with a browser "try it" console.

Whether a given call works for your key comes down to the scopes its permission bundle carries: a 403 with scope_denied names the missing scope, and a 403 with not_on_public_api means the operation is console-only and not part of the public surface at all. Start with the Quickstart to prove the loop end to end.

Keeping your key safe

• Never put it in front-end code or commit it to a repo. Keep it in a server-side secret or environment variable.
• Lost it or leaked it? Delete the key in settings and create a new one. The old one stops working immediately.
• You can have more than one key, for example one per script, so you can revoke them independently.