All /v1 endpoints (except /v1/openapi.json and /v1/llms.txt) authenticate with a bearer token, sent as an Authorization: Bearer <token> header. Two credential types are equal first-class paths:

• OAuth 2.0 access tokens — issued through the OAuth authorization flow. Preferred by Claude.ai, ChatGPT, and other MCP hosts that discover OAuth automatically.
• API keys — start with at_, created under Settings → System → API & MCP. Preferred by Cursor, Claude Code, and clients that set request headers.

Each API key is assigned to a service account; every request executes as that service account, with its permissions, not as the person who created the key. OAuth 2.0 tokens act as the authenticated user instead. Keep credentials secret: never expose them in client-side code or public repositories.

Send the token as an Authorization header on every request:

curl https://api.agencytitan.com/v1/clients \
  -H "Authorization: Bearer at_your_api_key_here"

const res = await fetch("https://api.agencytitan.com/v1/clients", {
  headers: { Authorization: "Bearer at_your_api_key_here" },
});
const data = await res.json();

import requests

res = requests.get(
    "https://api.agencytitan.com/v1/clients",
    headers={"Authorization": "Bearer at_your_api_key_here"},
)
data = res.json()

$ch = curl_init("https://api.agencytitan.com/v1/clients");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer at_your_api_key_here"]);
$data = json_decode(curl_exec($ch), true);

require "net/http"
require "json"

uri = URI("https://api.agencytitan.com/v1/clients")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer at_your_api_key_here"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
data = JSON.parse(res.body)

A missing, invalid, expired, or revoked token returns 401 with an OAuth-style body:

{
  "error": "invalid_token",
  "error_description": "The access token is invalid."
}

Send requests to the base URL https://api.agencytitan.com over HTTPS. The API is resource-oriented and uses standard verbs: GET to read, POST to create, PUT to set a desired state, PATCH to update, and DELETE to remove.

Request bodies are JSON. Send a Content-Type: application/json header on POST, PUT, and PATCH requests. Path parameters are described by each operation.

Requests are strictly validated: unknown query parameters or body properties, and out-of-range values, are rejected with a 400 (see Errors). Send only the documented fields.

curl -X POST https://api.agencytitan.com/v1/clients \
  -H "Authorization: Bearer at_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Co", "profile_id": "123e4567-e89b-12d3-a456-426614174000" }'

const res = await fetch("https://api.agencytitan.com/v1/clients", {
  method: "POST",
  headers: {
    Authorization: "Bearer at_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Acme Co",
    profile_id: "123e4567-e89b-12d3-a456-426614174000",
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api.agencytitan.com/v1/clients",
    headers={"Authorization": "Bearer at_your_api_key_here"},
    json={"name": "Acme Co", "profile_id": "123e4567-e89b-12d3-a456-426614174000"},
)
data = res.json()

Every response is JSON wrapped in a data envelope. Single-item endpoints return the object directly under data. List endpoints return an array under data alongside a pagination object (see Pagination). The examples show each shape.

Single item

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Co"
  }
}

List

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Acme Co"
    }
  ],
  "pagination": {
    "total": 120,
    "limit": 50,
    "offset": 0
  }
}

Successful reads and writes return 200. Failures use conventional HTTP status codes and a consistent error body (see Errors).

The API uses conventional HTTP status codes: 2xx for success, 4xx for a problem with the request, and 5xx for an error on our side. Requests are strictly validated: unknown or out-of-range query parameters and body properties are rejected with a 400.

Most errors return the standard envelope, whose type field you can branch on. The type is one of validation_error, permission_denied, not_found, conflict, rate_limited, or internal. Authentication failures (401) use an OAuth-style shape instead. Both shapes are shown alongside.

Error envelope

{
  "error": {
    "type": "validation_error",
    "message": "Human-readable description."
  }
}

Authentication error (401)

{
  "error": "invalid_token",
  "error_description": "..."
}

Status codes: 400 validation failed, 401 missing or invalid token, 403 insufficient permission, 404 not found, 409 conflict, 429 rate limited, 500 internal error.

List endpoints use offset pagination via the limit (1-200, default 50) and offset (default 0) query parameters, alongside sort and order. Request the next page by advancing offset by limit.

curl "https://api.agencytitan.com/v1/clients?limit=50&offset=0" \
  -H "Authorization: Bearer at_your_api_key_here"

const res = await fetch(
  "https://api.agencytitan.com/v1/clients?limit=50&offset=0",
  { headers: { Authorization: "Bearer at_your_api_key_here" } },
);
const data = await res.json();

import requests

res = requests.get(
    "https://api.agencytitan.com/v1/clients",
    params={"limit": 50, "offset": 0},
    headers={"Authorization": "Bearer at_your_api_key_here"},
)
data = res.json()

A list response carries the data array plus a pagination object with the total count. Single-item endpoints return { "data": { ... } } with no pagination.

Pagination response

{
  "data": [ ... ],
  "pagination": {
    "total": 120,
    "limit": 50,
    "offset": 0
  }
}

List endpoints accept a sort and an order parameter. sort selects the field to order by. The allowed values differ per resource, so check the sort parameter on each list endpoint. order is either asc or desc (defaults to desc).

curl "https://api.agencytitan.com/v1/clients?sort=name&order=asc" \
  -H "Authorization: Bearer at_your_api_key_here"

const res = await fetch(
  "https://api.agencytitan.com/v1/clients?sort=name&order=asc",
  { headers: { Authorization: "Bearer at_your_api_key_here" } },
);
const data = await res.json();

import requests

res = requests.get(
    "https://api.agencytitan.com/v1/clients",
    params={"sort": "name", "order": "asc"},
    headers={"Authorization": "Bearer at_your_api_key_here"},
)
data = res.json()

List endpoints support filtering. Where a search parameter is available it performs a free-text match (for example over a client's name and email). Resource-specific filters (such as status, priority_level, tags, or profile_id) are documented on each list endpoint.

Array filters accept multiple values: repeat the parameter to match any of several values (logical OR). Different query parameters are AND. On tasks and task-stages, first-class filters are also AND-merged with filter_group when both are sent.

curl "https://api.agencytitan.com/v1/clients?search=acme&status=active_client&status=lead" \
  -H "Authorization: Bearer at_your_api_key_here"

const params = new URLSearchParams({ search: "acme" });
params.append("status", "active_client");
params.append("status", "lead");
const res = await fetch(
  `https://api.agencytitan.com/v1/clients?${params}`,
  { headers: { Authorization: "Bearer at_your_api_key_here" } },
);
const data = await res.json();

import requests

res = requests.get(
    "https://api.agencytitan.com/v1/clients",
    params={"search": "acme", "status": ["active_client", "lead"]},
    headers={"Authorization": "Bearer at_your_api_key_here"},
)
data = res.json()

Task FilterGroup (filter_group)

GET /v1/tasks and GET /v1/task-stages also accept an advanced filter_group for nested AND/OR trees and custom fields. Prefer first-class params (priority_level, tags, status_scope, assignees, dates) when they are enough; those are AND-merged with filter_group when both are sent.

Pass filter_group as one URL-encoded JSON string:

{
  "logical_operator": "AND",
  "conditions": [
    { "field": "priority_level", "operator": "in_list", "value": ["high", "urgent"] },
    { "field": "field_values.budget", "operator": "greater_than", "value": "5000" }
  ],
  "groups": []
}

FILTER='{"logical_operator":"AND","conditions":[{"field":"field_values.budget","operator":"greater_than","value":"5000"}],"groups":[]}'
curl -G "https://api.agencytitan.com/v1/tasks" \
  -H "Authorization: Bearer at_your_api_key_here" \
  --data-urlencode "filter_group=${FILTER}"

const filterGroup = {
  logical_operator: "AND",
  conditions: [
    { field: "field_values.budget", operator: "greater_than", value: "5000" },
  ],
  groups: [],
};
const params = new URLSearchParams();
params.set("filter_group", JSON.stringify(filterGroup));
const res = await fetch(
  `https://api.agencytitan.com/v1/tasks?${params}`,
  { headers: { Authorization: "Bearer at_your_api_key_here" } },
);

System fields include status, priority_level, tags, assigned_to, client_id, process_definition_id, department_id, and date fields (due_date, created_at, and related). Custom fields use field_values.<field_key> (discover keys with GET /v1/fields). Option values come from GET /v1/tasks/options / GET /v1/tenant-context. See the filter_group parameter on GET /v1/tasks and GET /v1/task-stages for the full operator list.

Requests are rate limited per tenant to 600 requests per minute across all /v1 REST endpoints. Exceeding the limit returns a 429 response; the Retry-After header indicates how many seconds to wait before retrying.

Permissioned tenant audit activity, field history, and application events.

Application lifecycle events for currently readable resources.

Tenant-global custom-field values for the agency.

Explicit agency and personal information used to tailor AI responses.

AI preset discovery, canonical detail reads, and approval-gated deletion.

Prompt-free AI request metadata, costs, status, and safe errors.

Credential-bound, payload-free public API request observability.

Tenant-wide AI assignment feedback rules.

Task and ticket assignment decisions and governed reruns.

Metadata and short-lived download access for files attached to readable tenant entities.

Bounded authentication security events without raw network identifiers.

Read-only field, layout, icon, field-layout-template, and shortcode catalogs for typed authoring clients.

Automation authoring catalogs and graph lifecycle operations for creating, editing, organizing, and publishing automations.

Step-level automation execution outcomes.

Individual runs of an automation, with status and timing.

Governed direct-step probes, durable full automation test runs, progress, results, and safe sample hydration.

Automations are event-driven flows that run actions for you.

Read-only tenant billing truth: credit balance and status, transactions, client credits, and masked payment-method metadata.

Approval-ready management of client-owned payment methods; tenant platform-charge methods are excluded.

Approval-ready client-payment processor selection, capabilities, and allowlisted metadata.

Wallet and method-type presentation settings for client checkout.

Tenant auto-reload and billing contact settings, excluding platform charge-method replacement.

Durable, creator-owned planning, validation, review, and apply sessions for typed builder workflows.

Certificate templates issued for completed training and learning paths.

Tenant chat channels, direct messages, unread state, notification preferences, and membership.

ACL-scoped tenant chat messages, threads, reactions, read state, and governed message sending.

Caller-owned completion state for interactive SOP checklists.

Per-client billing behavior and financial-notification recipients.

Folders that organize notes within one client record.

Notes logged on client records.

Folders that organize client profiles for settings and authoring workflows.

Client profiles group your clients and define their custom fields and status options. A profile id is required when creating a client.

Processes attached to a client program, including effective schedules and exclusion state.

Automatic task-generation schedules attached to processes within program definitions.

Program enrollments: which programs each client is enrolled in, and their status.

Approval-gated bulk management of the service catalog: adding services to a category and deleting service categories.

Your agency's client records, including custom field values.

Server-side import of cloud-provider files into persistent tenant storage without exposing file payloads.

Threaded discussion comments attached to supported client, work, knowledge, training, and marketplace entities.

Folders that organize custom object definitions, including governed rehome-on-delete behavior.

Authorized incoming and outgoing links between custom-object records and supported core entities.

Directed links between records of agency-defined custom object types.

Records of your agency-defined custom object types, including field values.

Relationship definitions between custom object types, used to create record links.

Custom object definitions: the shape (fields) of your agency-defined record types.

Levels within an agency department, including order and explicit permission assignments.

Active and pending members assigned to agency departments and levels.

Your agency's departments and their configured levels.

Operational email-delivery metadata and explicitly permissioned content.

Effective-dated pay records for agency members. New records trim prior ones so pay history stays intact.

Working schedules for agency members: one schedule per member covering days, hours, and timezone.

Read-only layout structures for task stages, client profiles, views, modals, and forms.

Personal and tenant-wide pins for visible tenant entities.

Tenant routing, notification, and visibility settings for escalations.

Operational escalations, their lifecycle actions, participants, and follow-up next steps.

Folders that organize custom field definitions.

Clean field-level history for currently readable resources.

Custom field definitions that shape client (and other entity) data.

Submitted form responses, including the submitted field values.

Form definitions used to collect structured data.

Non-destructive crop and resize operations over tenant-owned raster images.

Credential-safe integration, endpoint, scope, and AI configuration catalogs.

Client invoices: drafts, line items, status transitions, and recorded payments.

Self-scoped knowledge-base engagement statistics.

Atomic, revision-safe patching and publication of canonical entity layouts.

Ordered training paths, their courses, and completion requirements.

Current-user training progress, certifications, and dashboard summaries.

Managed multipart uploads for escalation recordings and comment attachments.

Marketplace item actions with explicit destination-tenant and visibility enforcement.

Marketplace seller earnings destination and automatic-transfer preferences.

Modal definitions, resolved layouts, presentation settings, and actions.

The caller's own My Day plan and oversight snapshot: read-only primitives an agent can consult when the day plan or process exceptions matter.

Tenant-configurable navigation items, destinations, visibility, hierarchy, and ordering.

Tenant notification-template validation and test delivery.

Self-scoped notification inbox and explicit read-state commands.

Effective user permissions, access scopes, and the permission definitions catalog.

Bug, feature, and support feedback submitted to the platform team.

Compatibility operations for finding and managing process definitions.

Process blueprints that tasks are created from.

Running instances of process definitions and their field values.

Recurring service packages (programs) your agency offers.

Compatibility operations for recurring service program definitions.

Discoverable client-service categories and their tenant-scoped catalog details.

Folders that organize the tenant client-service category catalog.

Reusable read-only sections embedded in entity layouts.

Tenant and user signatures available for ticket replies.

Authenticated user feedback on visible standard operating procedures.

Folders used to organize standard operating procedures.

User reports and administrative resolution of outdated SOP content.

Caller-owned SOP ratings and tenant-safe aggregate rating statistics.

Advisory reviewer queues and durable SOP review decisions.

Tenant-defined tags used to categorize and filter standard operating procedures.

Caller-owned SOP viewing sessions and progress.

Standard operating procedures: your agency knowledge base.

Compatibility operations for process stage definitions and ordering.

Reusable status templates plus the scoped status, tag, and priority options used by tenant entities.

Tenant task audit history clipped by task permissions, scope, privacy, and definition access.

Read-only task auto-assignment configuration.

Stages (and substages) of a running task, showing where the work currently sits.

Tasks are running instances of your processes.

Tenant-wide AI availability and monthly spend controls.

One bootstrap call returning the reference data (profiles, users, client and task statuses/tags, status scopes, programs, processes) needed to ground ids before acting.

Effective ticket assignment routing and tenant configuration.

Rules that block or review matching inbound ticket messages.

Permissioned ticket communication delivery history.

Deliberately authorized additional recipients for a ticket thread.

Read-only ticket KPIs, time series, breakdowns, SLA breaches, and AI activity reports.

Internal ticket reply drafts and read-only manager-review queue information.

Inbound and outbound ticket endpoints, access controls, and delivery defaults.

Ticket intake decisions and sanitized sender previews.

Chronological ticket conversations, including external messages and internal notes.

Reusable tenant ticket reply templates and usage tracking.

Blocked inbound messages awaiting ticket intake review.

Ordered rules that route inbound tickets between inboxes.

Tenant-wide ticket AI, review, auto-close, and intake defaults.

Tenant ticket writing-style guidance used by drafting tools.

Rules that allow matching inbound messages to bypass intake blocks.

Support and work tickets.

Manual and automatically tracked work time, with task and entity attribution.

Redacted assessment runtime and server-graded learner attempts.

Issued training certificates visible through progress-reporting policy.

Training courses, their lifecycle, and folder placement.

Self-service learner enrollment and restart actions.

Folders used to organize training content.

Ordered authored content blocks within training lessons.

Lessons contained in training course modules.

Advisory manager-review queues and durable review decisions.

Ordered modules within training courses.

Immutable, server-graded lesson quiz attempts.

Tenant training behavior and completion settings.

Caller-owned absolute video playback progress.