Schema, usage and capabilities

These endpoints describe your workspace instead of returning its records. Call them when you build a query, before a large read, or when an action is refused and you want to know what is missing. None of them counts against your plan.

The MCP tools describe_schema and get_usage call the first two. See the tools reference.

GET /v1/schema

Required scope: contacts:read, companies:read or deals:read, matching entity.

Returns every field you can use in a typed filter, and the source fields you can sort by or group by in POST /v1/aggregate. The list depends on your workspace: it holds the standard properties, the fields of each source you have connected, and the columns of a connected database.

curl "https://api.pathbound.ai/v1/schema?entity=contacts" \
  -H "Authorization: Bearer $PATHBOUND_API_KEY"

{
  "status": "success",
  "entity": "contact",
  "connected_sources": ["apollo", "hubspot"],
  "filterable_fields": [
    {
      "field": "lifecyclestage",
      "source": "canonical",
      "type": "string",
      "ops": ["eq", "neq", "in", "nin", "exists", "contains"],
      "group_by": true,
      "pii": false,
      "filterable": true,
      "via": "materialized"
    },
    {
      "field": "createdate",
      "source": "canonical",
      "type": "date",
      "ops": ["eq", "neq", "in", "nin", "exists", "gt", "gte", "lt", "lte"],
      "group_by": true,
      "pii": false,
      "filterable": true,
      "via": "materialized"
    },
    {
      "field": "hubspot.hs_lead_status",
      "source": "hubspot",
      "type": "string",
      "ops": ["eq", "neq", "in", "nin", "exists", "contains"],
      "group_by": true,
      "pii": false,
      "filterable": true,
      "indexed": true,
      "via": "materialized"
    }
  ]
}

The standard properties are always listed, but a filter is not limited to them: any other property of a contact or a company can be named in a filter too. Its value is then compared as you sent it, without conversion to a type.

GET /v1/usage

Required scope: none. Any valid key can call it.

Returns how many active profiles your workspace has used in the current billing cycle and how many remain, and when each connected source last synced.

curl https://api.pathbound.ai/v1/usage \
  -H "Authorization: Bearer $PATHBOUND_API_KEY"

{
  "status": "success",
  "workspace": { "id": "tenant_xyz", "name": "Acme Corp", "ws": "acmecorp" },
  "activations_used": 1284,
  "remaining": 8716,
  "plan_cap": 10000,
  "cycle_start": "2026-10-02T00:00:00.000Z",
  "cycle_end": "2026-11-02T00:00:00.000Z",
  "reset_at": "2026-11-02T00:00:00.000Z",
  "subscription_status": "active",
  "plan_tier": "growth",
  "plan_label": "Growth",
  "entitlement_state": "subscribed",
  "is_trial": false,
  "trial_ends_at": null,
  "can_activate": true,
  "is_billing_exempt": false,
  "sources": [
    { "source": "apollo", "last_synced_at": "2026-10-12T09:41:07.000Z" },
    { "source": "hubspot", "last_synced_at": "2026-10-12T09:44:52.000Z" }
  ]
}

Records you have already read this cycle stay readable at any remaining, and counts, aggregates and id-only lists are always free. To learn what one particular read would add, use its dry_run.

GET /v1/tenant/capabilities

Required scope: actions:write

Returns which of the integrations that have action endpoints are connected (Gmail, Resend, Instantly, Apollo and Hunter) and, for each group of actions, whether the caller can use it now and why not. A connected CRM or another source that is only read is not listed here: GET /v1/usage lists those under sources. Call it when an action endpoint answers 412, or before you offer an action in your own interface.

Capabilities are answered for the user who created the key. Sending from Gmail is the clearest case: gmail.accounts lists every mailbox connected in the workspace, and send_enabled is true only for a mailbox that user connected themselves and may send from.

{
  "status": "success",
  "capabilities": {
    "integrations": ["gmail", "resend", "apollo"],
    "gmail": {
      "accounts": [
        {
          "account_id": "[email protected]",
          "is_primary": true,
          "has_send_scope": true,
          "needs_reconsent": false,
          "is_valid": true,
          "send_enabled": true
        }
      ]
    },
    "tool_settings": {
      "gmail_send_email": { "enabled": true, "sender_email": "[email protected]", "senders": ["[email protected]"] },
      "resend_send_email": { "enabled": false, "reason": "tool_disabled" },
      "prospecting_enrich": { "enabled": true, "providers": ["apollo"] },
      "apollo_sequences": { "enabled": false, "reason": "scope_missing" },
      "streams_manage": { "enabled": true }
    },
    "privacy": { "mcp_redact_pii": false },
    "cache_ttl_seconds": 60
  }
}

tool_settings holds one entry per group of actions; the example shows five of them. Each entry has enabled and, when it is false, a reason. For Gmail, sender_email is the mailbox a send without from would use, and senders every mailbox the caller may name. When enabled is true and there is no sender_email, several mailboxes can send and none is the default, so every send has to name one.

Each name under tool_settings stands for a switch on the MCP Tools page. Those switches are set for AI agents. Whether one also applies to an API key differs by action, and each action’s page says so: Gmail, Resend, Apollo sequences, Instantly, Enrichment and prospecting, Streaming and Knowledge.

privacy.mcp_redact_pii says whether the workspace hides contacts’ personal details from AI agents. It does not change what an API key receives.