generated: '2026-08-13'
method: searched
source: https://docs.inflection.io/api-reference/introduction
docs: https://docs.inflection.io/api-reference/introduction
summary: >-
  Cross-cutting request/response semantics for the Inflection Developer API — a JSON-over-HTTPS
  REST API under https://api.inflection.io/v1, authenticated with scoped Personal Access Tokens,
  wrapping every response in a consistent data/pagination/errors/meta envelope.
authentication:
  style: bearer-token
  header: Authorization
  format: Bearer <inf_pat_... | OAuth 2.1 access token>
  credential_types: [personal-access-token, oauth2-access-token]
  pat_permissions: [READ, WRITE]
  oauth_scopes: [inflection_app]
  oauth_model: OAuth 2.1 + PKCE (S256); the token acts as the authorizing user, so authorization is by role
  note: PATs do not work against the MCP server; MCP requires a connected app's OAuth flow.
  see: authentication/inflectionio-authentication.yml
idempotency:
  supported: false
  note: No idempotency-key header or parameter is documented or present in the OpenAPI. Contact writes are async and deduplicated by upsert semantics (batch upsert on email), not by an idempotency key.
pagination:
  style: page-number
  params:
    page_number: {default: 1, note: 1-based page index}
    page_size: {default: 20, max: 200}
  response_fields: [pageNumber, pageSize, totalElements, totalPages]
  location: pagination (present only on paged list endpoints)
response_envelope:
  fields:
    data: Payload — object or array; shape depends on the endpoint.
    pagination: Present only on paged list endpoints.
    errors: Populated on service-level failures (errorCode, message, detail).
    meta: {status: SUCCESS|FAILURE, timestamp: ISO-8601}
  note: Gateway-level auth errors (401/403) have no body at all; only service errors carry the envelope.
  field_case: snake_case (contact attributes under properties use snake_case keys)
async_writes:
  applies_to: [createContact, updateContact, batchUpsertContacts]
  model: Contact writes return HTTP 200 with a PENDING transaction (transactionId + status); poll GET /v1/contacts/transactions/{transactionId} until status is DONE.
  per_contact_status: [CREATED, UPDATED, NO_CHANGE, FAILED]
  unknown_transaction: NOT_EXIST (still HTTP 200)
  see: skills/inflectionio-sync-contact.md
versioning:
  scheme: uri-path
  current: v1
  base: https://api.inflection.io/v1
  see: lifecycle/inflectionio-lifecycle.yml
errors:
  envelope_field: errors[]
  code_field: errorCode
  format: custom (not RFC 9457 problem+json)
  see: errors/inflectionio-problem-types.yml
rate_limiting:
  documented: true
  limit: 1000 requests/second per workspace, shared by every credential (PATs and OAuth apps)
  usage_caps: none — no monthly quotas or total-call caps on the Developer API
  exhaustion_status: 429
  response_headers:
    documented: false
    note: >-
      No X-RateLimit-*, RateLimit-* or Retry-After headers are published. The only runtime signal is
      the 429 itself, so back-off must be time-based (exponential with jitter, per the docs).
  see: rate-limits/inflectionio-rate-limits.yml
partial_success:
  note: >-
    Two documented operations return HTTP 200 while carrying an error signal — addListMembers reports
    skipped ids in errors[] as CONTACTS_NOT_FOUND, and getContactTransaction returns status NOT_EXIST
    for an unknown id. Read the body, not just the status.
  see: errors/inflectionio-problem-types.yml
not_found_semantics:
  note: >-
    Not-found is inconsistent by resource: a missing contact is 400 BAS-E-002, a missing list or email
    is 404 NOT_FOUND. A mistyped path under /v1 is 401, not 404 (deny-by-default gateway).
field_case:
  contacts: snake_case under properties — camelCase keys are silently ignored and saved as null
  list_members: camelCase (firstName, companyName, phoneNumber) for the same person
  note: The two resources disagree on field case for identical attributes; map explicitly per endpoint.
request_tracing:
  documented: false
agent_surface:
  mcp: https://mcp.inflection.io/ (OAuth 2.1 only)
  see: mcp/inflectionio-mcp.yml