> ## Documentation Index > Fetch the complete documentation index at: https://docs.teamfollowup.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the public API base URL: https://api.teamfollowup.ai/api. > Authenticate public API requests with Authorization: Bearer YOUR_API_KEY. > Use product-owned terms: agents, campaigns, projects (GoHighLevel sub-accounts), contacts, calls, outcomes, skills, cadences, phone numbers. > Scope requests by locationId rather than projectName. > Read the guide linked from each API reference group before recommending an endpoint. # Set TFU Live agent orb colour > TFU Live only. Choose the colours of the agent’s orb: default (it follows the voice), curated (derived from the agent id), one of the preset pairs, or two custom #rrggbb colours. Cosmetic: no ifVersion, no new revision or change history entry, and allowed while the agent is live. The answer is the choice as Get TFU Live agent returns it in orb. Anything but one of the four shapes is refused with 422. Required scope: `agents:write`. Required API key scope: `agents:write`. ## OpenAPI ````yaml /openapi.yaml put /api/tfu-live-agents/{id}/orb openapi: 3.1.0 info: title: TFUAI Server API version: 1.0.0 description: >- API reference for the TFUAI SaaS server. All published endpoints are mounted under `/api`. Responses use a standard envelope: `{ "success": true, ... }` on success and `{ "success": false, "error": "..." }` on failure. Product API modules are being launched module by module. This spec currently exposes only contracted public modules. Authenticate public API requests with an API key in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. servers: - url: https://api.teamfollowup.ai description: Production API origin. Public API paths are under /api. security: [] tags: - name: Agents description: >- Build the conversation: identity and settings, script, lead context and split testing. - name: Analytics description: >- Understand call volume, pickup, booking and transfer metrics within the selected reporting scope. - name: Billing description: >- Balances, spend, purchases and sub-account rebilling. Reference and guides only; the builder chatbot has no billing playbook. - name: Calls description: >- Review completed calls, recordings, transcripts and campaign run history; distinguish observation from placing a new call. - name: Campaigns description: >- Configure what starts calls, who is eligible, calling windows, caller IDs, activation and the actions that follow each outcome. What runs after a call lands: for each outcome (booked, opted out, asked for a callback…), an ordered chain of actions — tag the contact, move a pipeline stage, send an SMS, book an appointment. Stored as a graph: `nodes` are the actions, `edges` say what follows what, and `dispositionEntries` maps each outcome to the node its chain starts at. **Pick the narrowest endpoint that does the job.** | To | Call | | | --- | --- | --- | | See what fires per outcome | `GET .../workflow?view=summary` | Reads as plain text, no graph walking | | Add steps to an outcome | `POST .../outcomes/{outcome}/nodes` | Server derives node ids, edge ids, handles, layout | | Change a message, tag or setting | `PATCH .../workflow` | Merges; carries no graph, so it cannot damage one | | Remove one step | `DELETE .../nodes/{nodeId}` | Also re-links the chain around it | | Author or replace the whole graph | `PUT .../workflow` | Replaces everything you send | `PUT` is the only one that can re-wire, position nodes, build an `if`, save an unconfigured draft, or copy a whole workflow — and the only one that can overwrite a change someone else made after you read it. Use it when you are genuinely authoring the graph, and send `expectedVersion` when you do. For everything else the narrower endpoints are both easier and safer. - name: Contacts description: >- Find contacts and their calls, manage do-not-call status and identify internal contacts excluded from reporting. - name: In-call Capabilities description: >- Configure actions and instructions the agent uses during a live call: booking, transfers, lookups and custom skills. - name: Master agent description: >- Run a shared agent and campaign across linked projects; manage inheritance, local bindings, synchronization and rollout readiness. - name: Native Calendar description: >- The diary of a sub-account with no CRM: its bookable calendars, the free slots they offer, and the appointments on them. Availability is computed per request against live bookings and is never cached, because a cached slot is one somebody else has already taken. - name: Native Contacts description: >- The people a sub-account with no CRM calls, and the fields it keeps on them. This is the system of record for those contacts: there is nowhere else they exist. A sub-account with a CRM keeps its contacts there and every operation here answers 400 for it. - name: Phone Numbers description: >- Find and manage caller IDs, assign numbers to campaigns and understand connected Twilio numbers. - name: Projects description: >- Understand project ownership, inspect configuration and validate the local resources used by a campaign. - name: TFU Live description: >- Build one TFU Live agent with its Brain, Voice and equipped actions; connect it through shared Campaigns. - name: Voices description: >- Browse the voice catalogue and select a voice; configure speech and listening behavior in Agents. paths: /api/tfu-live-agents/{id}/orb: put: tags: - TFU Live summary: Set TFU Live agent orb colour description: >- TFU Live only. Choose the colours of the agent’s orb: default (it follows the voice), curated (derived from the agent id), one of the preset pairs, or two custom #rrggbb colours. Cosmetic: no ifVersion, no new revision or change history entry, and allowed while the agent is live. The answer is the choice as Get TFU Live agent returns it in orb. Anything but one of the four shapes is refused with 422. Required scope: `agents:write`. Required API key scope: `agents:write`. operationId: put-tfu-live-agents-by-id-orb parameters: - name: locationId in: query required: true schema: type: string description: >- Sub-account belonging to the authenticated agency and any narrower credential location binding. - name: id in: path required: true schema: type: string description: TFU Live agent id. Never use an ordinary provider agent id. requestBody: description: >- Exactly one orb shape. Any other key, a missing or extra preset or colors, an unknown preset, or anything but two #rrggbb colours is refused. required: true content: application/json: schema: $ref: '#/components/schemas/TfuLiveOrb' examples: default: value: style: default curated: summary: Derived from the agent id value: style: curated preset: summary: A preset pair value: style: preset preset: harvest custom: summary: Two colours of your own value: style: custom colors: - '#0EA5E9' - '#6366f1' responses: '200': description: The orb colour now saved, as Get TFU Live agent returns it in orb. content: application/json: schema: $ref: '#/components/schemas/TfuLiveOrbResponse' example: success: true data: orb: style: preset preset: harvest '400': description: >- TFU Live request rejected: { success: false, error, code, workflowId?, stepId?, field?, setupItems? }. Read the error and current agent before retrying. content: application/json: schema: $ref: '#/components/schemas/TfuLiveError' example: success: false error: locationId is required. code: invalid_request '401': description: >- TFU Live request rejected: { success: false, error, code, workflowId?, stepId?, field?, setupItems? }. Read the error and current agent before retrying. content: application/json: schema: $ref: '#/components/schemas/TfuLiveError' example: success: false error: Unauthorized message: Access token is required. Please login '403': description: >- TFU Live request rejected: { success: false, error, code, workflowId?, stepId?, field?, setupItems? }. Read the error and current agent before retrying. content: application/json: schema: $ref: '#/components/schemas/TfuLiveError' example: success: false error: InsufficientScope message: This API key does not have the required scope. requiredScope: agents:write '404': description: >- TFU Live request rejected: { success: false, error, code, workflowId?, stepId?, field?, setupItems? }. Read the error and current agent before retrying. content: application/json: schema: $ref: '#/components/schemas/TfuLiveError' example: success: false error: Agent not found. code: not_found '422': description: >- TFU Live request rejected: { success: false, error, code, workflowId?, stepId?, field?, setupItems? }. Read the error and current agent before retrying. content: application/json: schema: $ref: '#/components/schemas/TfuLiveError' examples: unknownPreset: value: success: false error: >- Choose one of the preset orb colours: watermelon, harvest, lofi, guava, tropical, truffle, horizon, lotus, retro, tide, pop, yacht, cobalt, northern, amethyst, orchard, berries. code: invalid_agent customColours: value: success: false error: >- A custom orb takes exactly two colours, each written as #rrggbb. code: invalid_agent extraKey: value: success: false error: A curated orb takes only style. code: invalid_agent '429': description: >- TFU Live request rejected: { success: false, error, code, workflowId?, stepId?, field?, setupItems? }. Read the error and current agent before retrying. content: application/json: schema: $ref: '#/components/schemas/TfuLiveError' example: success: false error: TooManyRequests message: Too many write requests, please slow down. '502': description: >- TFU Live request rejected: { success: false, error, code, workflowId?, stepId?, field?, setupItems? }. Read the error and current agent before retrying. content: application/json: schema: $ref: '#/components/schemas/TfuLiveError' example: success: false error: Agent identity could not be verified. code: provider_unavailable '503': description: >- TFU Live request rejected: { success: false, error, code, workflowId?, stepId?, field?, setupItems? }. Read the error and current agent before retrying. content: application/json: schema: $ref: '#/components/schemas/TfuLiveError' example: success: false error: Agent identity could not be verified. code: provider_unavailable security: - ApiKeyAuth: [] x-codeSamples: - lang: bash label: cURL source: |- curl --request PUT \ --url https://api.teamfollowup.ai/api/tfu-live-agents/{id}/orb \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "style": "default" }' components: schemas: TfuLiveOrb: description: >- The colours of the agent’s orb, exactly one of four shapes. default: it follows the voice, purple and pink for a female voice, blue and cyan for a male one, indigo and mint for a voice that is neither; curated: colours derived from the agent id, the same on every screen; preset: one of 17 pairs from published palettes, each the palette’s first real colour as the main colour and the next colour that differs from it as the glow; custom: two colours of your own, the orb’s own colour then its glow. Cosmetic: it changes nothing the agent says or does. oneOf: - type: object required: - style additionalProperties: false description: Follows the voice. An agent that never chose reads as this. properties: style: const: default - type: object required: - style additionalProperties: false description: Colours derived from the agent id. properties: style: const: curated - type: object required: - style - preset additionalProperties: false description: >- One of 17 pairs from published palettes: the palette’s first real colour is the main colour, the next colour that differs from it the glow. properties: style: const: preset preset: type: string enum: - watermelon - harvest - lofi - guava - tropical - truffle - horizon - lotus - retro - tide - pop - yacht - cobalt - northern - amethyst - orchard - berries description: >- The preset’s id. The TFU Live voice guide gives each pair’s two colours, their hex values, and the palette and positions they come from. - type: object required: - style - colors additionalProperties: false description: 'Two colours of your own: the orb’s own colour, then its glow.' properties: style: const: custom colors: type: array minItems: 2 maxItems: 2 items: type: string pattern: ^#[0-9a-fA-F]{6}$ description: >- Exactly two colours as #rrggbb: the first is the orb’s own colour, the second its glow. Upper case is accepted; they are stored and read back in lower case. TfuLiveOrbResponse: type: object required: - success - data properties: success: const: true data: type: object required: - orb additionalProperties: false properties: orb: $ref: '#/components/schemas/TfuLiveOrb' additionalProperties: false TfuLiveError: type: object required: - success - error properties: success: const: false error: type: string description: >- What to do about it, in words. A status-wide gate (authentication, scope, rate limit) may use its own error name with a message. code: type: string enum: - invalid_workflow - setup_incomplete - workflow_resource_not_found - workflow_resource_unavailable - workflow_secret_refused - invalid_agent - invalid_request - unauthorized - insufficient_balance - forbidden - not_found - conflict - too_large - provider_unavailable - internal_error - AGENT_OPERATION_UNSUPPORTED - TFU_LIVE_CAMPAIGN_PENDING description: >- The kind of refusal: invalid_workflow (a workflow’s structure or a node’s settings), setup_incomplete (a setting still to fill or a Brain template placeholder still in the prompt, where the agent must be complete: preparing it, or a save that sets it up; setupItems lists every one), workflow_resource_not_found (a calendar, custom field, pipeline stage, team or rep the sub-account lacks, or an inactive calendar), workflow_resource_unavailable (503: the sub-account’s resources could not be read; retry), workflow_secret_refused (a secret header rule), invalid_agent (any other part of the agent), else by status. TFU_LIVE_* names a product state. workflowId: type: string description: >- The workflow a workflow refusal is about. Absent on a workflow being created, which has no id yet. stepId: type: string description: The step inside it. field: type: string description: >- The setting inside the step: calendarId, routing[1].calendarId, items[0].field, destination.teamId, headers.Authorization; brain.prompt for a placeholder. On a create from a Brain template, the request value: values., values or brainTemplateId. setupItems: type: array items: type: object required: - kind - message additionalProperties: false description: >- Something the agent still needs before it can be prepared for real calls. properties: kind: type: string enum: - workflow_setting - prompt_placeholder description: >- workflow_setting: a setting still to fill (a calendar, a tag, who takes a transfer, zip codes, a choice’s answers, an item’s label); prompt_placeholder: a Brain template [bracketed] placeholder still in the prompt (legacy: templates no longer hold any). workflowId: type: string workflowName: type: string stepId: type: string node: type: string description: The node type. field: type: string description: >- The setting inside the step (calendarId, destination, items[0].choices), or brain.prompt. placeholder: type: string message: type: string description: What to do, in words. description: >- On setup_incomplete: everything the agent still needs, the first of which the refusal names. additionalProperties: {} securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API key description: 'Send your API key as `Authorization: Bearer YOUR_API_KEY`.' ````