# Start here for AI agents Source: https://docs.aioncx.com/agents/quickstart Discover AionCX documentation, select the right scoped credential, and complete Mach-1 or Atlas tasks through existing APIs and MCP tools. An authorized agent can discover supported AionCX operations, submit work, and retrieve its results through REST or MCP. Start with the task and input, use the credential for that domain, and follow the returned state to a useful result. ## 1. Read the current documentation This documentation site exposes a public `/llms.txt` index and a separate `/mcp` documentation-search endpoint. Connect that endpoint in clients that support it, or follow the index and page links directly. Documentation search reads instructions. Product processing uses the application endpoint below. ## 2. Select the connection | Task | Connection and credential | | - | - | | Search these public docs | This site's documentation MCP | | Transcribe or analyze conversations | `https://build.aioncx.com/api/mcp` with an `atlas_ingest_` scoped key | | Submit or read Mach-1 forecasts | The same application MCP with explicitly granted `forecast:submit` / `forecast:read` | | Use native Atlas workforce operations | Your organization's Atlas `/api/mcp` with an `atlas_mcp_` connection and the relevant workspace/domain grants | | Use Workforce REST | The native external connection also needs explicit `api:connect` | A person establishes the account, verifies email, configures sources, creates the connection, and funds the account when required. Store the supplied credential in the client environment or secret configuration. ## 3. Discover tools A standard MCP client initializes the connection and calls `tools/list`. The server returns tools visible under that credential's current authority. For a direct discovery check, set `MACH1_API_KEY` and `MACH1_MCP_URL` in the environment. Use the workspace query selector on the URL when the key grants multiple workspaces. ```bash theme={"system"} curl --fail-with-body "$MACH1_MCP_URL" \ -H "Authorization: Bearer $MACH1_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-06-18' \ --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' ``` ## 4. Complete a task ### Transcribe and analyze a conversation 1. Use `mach1_get_transport` for upload endpoints and limits. 2. Use `mach1_list_analysis_definitions` when analysis is required. Select real published version IDs; an omitted list requests no analysis. 3. Submit an audio URL or transcript with the caller's saved idempotency key. Local audio bytes and oversized transcripts use direct receiver transport. 4. Retain the interaction ID and revisions. Poll `mach1_get_status`. 5. Read `mach1_get_transcript` and `mach1_get_results`, following pagination and citing evidence. See [transcription](/mach1/transcription), [analysis](/mach1/analysis), and [results](/mach1/results). ### Request a forecast 1. For registered metrics, use `mach1_list_forecast_sources` with the authorized workspace. 2. Construct the numerical or metric request described in [forecasting](/mach1/forecasting). 3. Call `mach1_submit_forecast` with `request` and the caller's saved `idempotency_key`. 4. Retain `run_id` and the returned price. 5. Poll `mach1_get_forecast`, then retrieve every result page with the same quantile selection. ### Prepare workforce work in Atlas Begin with `atlas_discover_workforce`. Review the source evidence, use the existing setup preview where needed, then use the paired staffing, draft, and publication operations your connection is granted. Follow the [Workforce contract](/api-reference/workforce/overview) for exact selectors, recoverable keys, current-source checks, and publication states. The [operator guide](/atlas/resource-management) explains the same work in application terms. ## 5. Report the outcome State the task, saved request/run ID, result state, useful findings or forecast, and relevant limitations. Cite available source evidence. Distinguish a completed result from accepted work still waiting to run. After an uncertain submission, retry the original payload with its original key. Explain a funding or permission blocker and direct the person to the appropriate screen. Billing-ledger reconciliation requires an authorized billing view; scoped result access alone does not supply it. The [Mastra example](/mach1/mastra) provides an executable client. Setup, funding, and key replacement remain human setup steps in that example. # Apply one exact saved native assessment command Source: https://docs.aioncx.com/api-reference/apply-one-exact-saved-native-assessment-command /api-reference/workforce/openapi.json post /api/v1/workforce/setup/apply The selected assessment must belong to this token owner in this workspace. Reads the command from existing Agent Kernel evidence; rejects configuration substitution. Each selected command already has a stable key, so no separate Idempotency-Key is used. Current native authority and assessment revision are rechecked transactionally. Replay may recover a committed effect after later corrections. # Authentication Source: https://docs.aioncx.com/api-reference/authentication Human sessions, scoped Mach-1 keys and native workforce integrations. [Build](https://build.aioncx.com) uses a verified email/password session. Confirm your email before Build creates a workspace. Existing invited people retain their existing workspace selection. The browser session is used for key management, source setup, Requests and billing. Create a **personal ingest key** in Build → Developers. The secret appears once. A key can submit and read or be read-only, has a workspace grant and an expiry (90 days by default, or explicitly until revoked). Current person membership and capabilities are checked at each call; a token does not restore access that its owner has lost. Revoke or replace the key in Build. Do not put keys in source control, URLs, logs or an agent prompt. For the Mach-1 REST and MCP endpoints, send `Authorization: Bearer `. Personal keys use their granted workspace; send `X-Workspace-Id` for receiver submissions and scoped reads when needed. Organization keys with multiple workspace grants must select an allowed workspace using the route's workspace selector. API, Deepgram and native Zoom reads also enforce their own subject visibility; an organization ingest key cannot read native Zoom interactions. The common `/api/mcp` URL supports distinct credentials. **Mach-1 MCP** uses `atlas_ingest_` scoped keys. Visible tools follow the conversation and forecasting permissions granted to that key. The existing workforce/scheduling branch uses `atlas_mcp_` connections with separate grants. See [MCP](/integrations/mcp). Original audio uploads and direct transcripts go to the receiver URL discovered in Build, not through the Atlas status API. Build uses its authenticated cookie for its human routes under `/api/atlas/ingest`; external clients use bearer-key routes under `/api/ingest`. A browser cookie is not a scoped API key. ## Forecasting permissions In Build → Developers, enable **Submit forecasts** and **Read forecasts** for the intended key. These grant `forecast:submit` and `forecast:read`; conversation permissions alone do not grant them. Forecasting REST uses `workspace_id` in the query string. MCP uses the connection workspace selector and the tool's declared workspace input where required. Current workspace and source authority are rechecked. See [forecasting](/mach1/forecasting). ## Workforce integrations Workforce REST under `/api/v1/workforce` requires `atlas_mcp_` with explicit `api:connect` and the existing workspace/domain grants. `mcp:connect` alone never permits REST. Explicit integrations default to 90 days; narrowly scoped single-workspace planning connections can explicitly be until revoked. Ordinary MCP defaults remain unchanged. Both transports recheck current owner authority and use a token Actor for effects. See the [workforce contract](/api-reference/workforce/overview). Complete or reconcile issued workforce drafts before rotating the connection: rotation revokes the old key and gives the successor a distinct token Actor, so it cannot recover the predecessor's pending requests. Authorized native users retain access to the existing receipts. # Commit issued draft exactly once Source: https://docs.aioncx.com/api-reference/commit-issued-draft-exactly-once /api-reference/workforce/openapi.json post /api/v1/workforce/draft-requests/{requestKey}/commit No body. Header key must equal path key. Rechecks current authority and native source revisions; identical replay returns the existing result. Does not publish. # Compute and persist staffing evidence Source: https://docs.aioncx.com/api-reference/compute-and-persist-staffing-evidence /api-reference/workforce/openapi.json post /api/v1/workforce/scheduling-groups/{groupId}/requirements/compute Native recomputation, not a schedule commitment. Requires authored manual demand or completed forecast evidence; does not start inference. Staffing rows retain the latest computation; this operation is not an exactly-once staffing receipt. # Create a dated member atomically Source: https://docs.aioncx.com/api-reference/create-a-dated-member-atomically /api-reference/workforce/openapi.json post /api/v1/workforce/scheduling-groups/{groupId}/members Requires workforce write and current manage_workforce_roster. Subject is nested and never identifies the acting principal. Enforce mode requires employment_assignment_id. Validates current assignment, person, overlap and FTE; any needed Agent slot rolls back with a failed membership. # Create a scheduling group atomically Source: https://docs.aioncx.com/api-reference/create-a-scheduling-group-atomically /api-reference/workforce/openapi.json post /api/v1/workforce/scheduling-groups Requires workforce write and current manage_schedules. Creates the native group and object together. Optional forecast_group_operation_key binds the latest reviewed forecast publication; a missing or superseded publication is refused. # Delete the issuing Person’s setup run Source: https://docs.aioncx.com/api-reference/delete-the-issuing-person’s-setup-run /api-reference/workforce/openapi.json delete /api/v1/workforce/setup/assessment Requires workforce write and current manage_schedules authority. Closes only the token owner’s setup run in this workspace, attributes the request to its token Actor, then uses existing native conversation cleanup. Saved configuration, schedules and command receipts remain. An absent or foreign ID returns the same idempotent success. A closed run awaiting lease/storage cleanup returns cleanupPending=true and is no longer listed. No publication grant is required. # Import a public audio URL Source: https://docs.aioncx.com/api-reference/direct-submission/import-a-public-audio-url /api-reference/mach1/openapi.json post /v1/ingest/audio-url Submit a public audio URL for asynchronous ingestion in the selected workspace. # Submit existing text or turns Source: https://docs.aioncx.com/api-reference/direct-submission/submit-existing-text-or-turns /api-reference/mach1/openapi.json post /v1/ingest/transcripts Submit existing transcript text or speaker turns for asynchronous analysis without uploading audio. # Upload original audio Source: https://docs.aioncx.com/api-reference/direct-submission/upload-original-audio /api-reference/mach1/openapi.json post /v1/ingest/audio Submit an original WAV, MP3, or M4A recording for asynchronous processing in the selected workspace. # Discover provider connections Source: https://docs.aioncx.com/api-reference/discover-provider-connections /api-reference/workforce/openapi.json get /api/v1/workforce/connections Requires separate provider-read and current provider setup authority. # Discover workforce facts before WFM configuration Source: https://docs.aioncx.com/api-reference/discover-workforce-facts-before-wfm-configuration /api-reference/workforce/openapi.json get /api/v1/workforce/discovery Count-checked, read-only canonical Queue and membership inventory. Source, Person and semantic sections explicitly report denied or unavailable evidence. Summary returns totals and decisions; queue/person views return bounded detail pages after the same complete internal enumeration. No configuration is created. # List executable published Definition versions Source: https://docs.aioncx.com/api-reference/discovery/list-executable-published-definition-versions /api-reference/mach1/openapi.json get /api/ingest/analysis-definitions List published analysis Definition versions available for direct submission. # Errors Source: https://docs.aioncx.com/api-reference/errors Design resilient clients while the Atlas v1 error contract is finalized. The canonical external error envelope and status-code matrix are forthcoming. Endpoint documentation will define expected failures alongside each operation. ## Client behavior Until a specific contract is published, integration clients should follow conservative HTTP practices: * treat only documented outcomes as success; * set explicit timeouts; * retry only operations documented as safe to retry; * use bounded exponential backoff with jitter; * avoid logging credentials or sensitive payloads; * retain correlation metadata returned by Atlas; * surface validation and permission failures to an operator. ## Failure categories Plan for authentication or authorization, validation, not found, conflict, rate limit, and internal error categories. The exact status codes and response fields will be documented with the API reference. > [!NOTE] > > Do not build production parsing against an observed internal response. Only fields documented here after publication should be considered stable. # Evaluate staffing read-only Source: https://docs.aioncx.com/api-reference/evaluate-staffing-read-only /api-reference/workforce/openapi.json post /api/v1/workforce/scheduling-groups/{groupId}/requirements/evaluate Requires ready source evidence; does not start a prediction or persist requirements. 1–14 inclusive dates. # Forecasting REST API Source: https://docs.aioncx.com/api-reference/forecasting/overview Submit a bounded Mach-1 forecast and retrieve its saved status and results using scoped forecast permissions. The Mach-1 forecasting API accepts numerical history or a registered metric and returns a saved prediction run. REST and MCP use the same request schema, prediction execution, and retained results. | Operation | REST | MCP | | - | - | - | | Submit a forecast | `POST /api/forecasts?workspace_id=...` | `mach1_submit_forecast` | | Read status/results | `GET /api/forecasts/{runId}?workspace_id=...` | `mach1_get_forecast` | | Discover registered metric sources | Use the forecast-source MCP discovery tool | `mach1_list_forecast_sources` | Create a scoped key in **Build → Developers** with the applicable **Submit forecasts** and **Read forecasts** permissions. Send `Authorization: Bearer `. The forecasting REST selector is the `workspace_id` query parameter; conversation APIs have their own workspace selectors. ## Request Send the `ForecastRequestSchema` body with a stable `Idempotency-Key`. Its `method` defaults to `auto` and its `source.type` selects `numerical` or `metric`. The [generated OpenAPI reference](/api-reference/forecasting/openapi.json) describes the input schema and endpoints. Numerical input supplies an interval, timezone, history start, horizon, and aligned target series. Metric input supplies the discovered metric and object type, history window, interval, horizon, and optional dimensions, filters, and declared companion inputs. ## Response Submission returns `run_id`, `status`, the retained `price`, and `results_url`. Draft, queued, and running submissions return HTTP 202; other returned states use HTTP 200. Read responses contain `run_id`, `status`, `method`, `method_version`, `rows`, and `next_cursor`. Before completion, rows are empty because the run is still processing. A failed run returns `error: "forecast_failed"`. Completed rows include series/dimensions, interval bounds, operational point, available interval bounds, and selected quantiles with their interpretation metadata. The default read page is 50 rows with P05, P50, and P95. Available uncertainty depends on the method and result. ## Errors | HTTP status | Meaning | | - | - | | 400 | Invalid JSON, unsupported forecast input, invalid cursor, or invalid quantile selection | | 401 | Invalid or expired credential | | 403 | Missing forecast grant, workspace access, or current source authority | | 404 | Forecast unavailable to this reader | | 409 | Idempotency key reused with different request content | | 413 | Request exceeds the transport boundary | | 415 | Submission content type must be application/json | | 503 | Forecast service unavailable; an uncertain submission can be retried with the same payload and key | REST errors use `{"error":"code"}`; unavailable service responses also include `retryable: true`. MCP has its own structured tool-error envelope. See the [task guide](/mach1/forecasting) for a complete synthetic request and [pricing](/mach1/forecasting-pricing) for current forecasting charges. # Inspect a scheduling group and members Source: https://docs.aioncx.com/api-reference/inspect-a-scheduling-group-and-members /api-reference/workforce/openapi.json get /api/v1/workforce/scheduling-groups/{groupId}/members Read a scheduling group and its member assignments. # Inspect native calendar preparation Source: https://docs.aioncx.com/api-reference/inspect-native-calendar-preparation /api-reference/workforce/openapi.json get /api/v1/workforce/connections/{connectionId}/preparation Read native calendar preparation details for a workforce provider connection. # Inspect native configuration delivery evidence Source: https://docs.aioncx.com/api-reference/inspect-native-configuration-delivery-evidence /api-reference/workforce/openapi.json get /api/v1/workforce/connections/{connectionId}/sync-status Read synchronization status and configuration delivery evidence for a workforce provider connection. # Inspect native draft request Source: https://docs.aioncx.com/api-reference/inspect-native-draft-request /api-reference/workforce/openapi.json get /api/v1/workforce/draft-requests/{requestKey} Read the state and evidence for a native draft request by its request key. # Inspect permissible owners, targets and calendars Source: https://docs.aioncx.com/api-reference/inspect-permissible-owners-targets-and-calendars /api-reference/workforce/openapi.json get /api/v1/workforce/forecast-groups/options List permissible owners, targets, and calendars for forecast group configuration. # Inspect provider inventory Source: https://docs.aioncx.com/api-reference/inspect-provider-inventory /api-reference/workforce/openapi.json get /api/v1/workforce/connections/{connectionId}/resources List resources from a selected workforce provider connection. # Inspect published forecast groups Source: https://docs.aioncx.com/api-reference/inspect-published-forecast-groups /api-reference/workforce/openapi.json get /api/v1/workforce/forecast-groups List published forecast groups in the selected workspace, with optional archived groups. # Inspect scheduling group and roster Source: https://docs.aioncx.com/api-reference/inspect-scheduling-group-and-roster /api-reference/workforce/openapi.json get /api/v1/workforce/scheduling-groups/{groupId} Read a scheduling group's configuration and roster. # Inspect workforce configuration evidence Source: https://docs.aioncx.com/api-reference/inspect-workforce-configuration-evidence /api-reference/workforce/openapi.json get /api/v1/workforce/readiness Counts are configuration evidence only. queue_settings contains dated native queue service goals, currently sourced from Zoom catalog attributes, using count-checked pagination for all active queues. Missing or conflicting fields remain unknown. This does not establish observed performance, source freshness or qualified roster completeness. # List or discover authorized interactions Source: https://docs.aioncx.com/api-reference/interactions/list-or-discover-authorized-interactions /api-reference/mach1/openapi.json get /api/ingest/interactions Identifier filters are mutually exclusive. An external ID may match multiple source actors or connections. A filtered cursor is bound to these filters. # Read authorized recording Source: https://docs.aioncx.com/api-reference/interactions/read-authorized-recording /api-reference/mach1/openapi.json get /api/ingest/interactions/{interactionId}/recording Read recording details for an authorized interaction. Reads may return lossless parts with next_cursor when large. Cursors pin input and transcript revisions. Native Zoom additionally requires recording visibility. # Read authorized results Source: https://docs.aioncx.com/api-reference/interactions/read-authorized-results /api-reference/mach1/openapi.json get /api/ingest/interactions/{interactionId}/results Read analysis results for an authorized interaction. Reads may return lossless parts with next_cursor when large. Cursors pin input and transcript revisions. Native Zoom additionally requires recording visibility. # Read authorized status Source: https://docs.aioncx.com/api-reference/interactions/read-authorized-status /api-reference/mach1/openapi.json get /api/ingest/interactions/{interactionId}/status Read the processing status for an authorized interaction. Reads may return lossless parts with next_cursor when large. Cursors pin input and transcript revisions. Native Zoom additionally requires recording visibility. # Read authorized transcript Source: https://docs.aioncx.com/api-reference/interactions/read-authorized-transcript /api-reference/mach1/openapi.json get /api/ingest/interactions/{interactionId}/transcript Read the speaker-attributed transcript for an authorized interaction. Reads may return lossless parts with next_cursor when large. Cursors pin input and transcript revisions. Native Zoom additionally requires recording visibility. # Issue an exact native draft proposal Source: https://docs.aioncx.com/api-reference/issue-an-exact-native-draft-proposal /api-reference/workforce/openapi.json post /api/v1/workforce/draft-requests Persists issued request evidence; creates no shifts until commit. Requires usable authored demand and current requirements; unconfigured demand returns generation.demand_unavailable rather than a floor-only proposal. Maximum 14 dates and 200 roster entries. Native rules and source fencing remain authoritative. # List scheduling groups Source: https://docs.aioncx.com/api-reference/list-scheduling-groups /api-reference/workforce/openapi.json get /api/v1/workforce/scheduling-groups List scheduling groups in the selected workspace. # List the issuing Person’s ten latest setup sessions in this workspace Source: https://docs.aioncx.com/api-reference/list-the-issuing-person’s-ten-latest-setup-sessions-in-this-workspace /api-reference/workforce/openapi.json get /api/v1/workforce/setup/assessments Lists the issuing Person’s ten latest setup runs in creation order within the selected workspace. Opening a run does not make it the newest. Closed runs are omitted. # AionCX API overview Source: https://docs.aioncx.com/api-reference/overview Find Mach-1 conversation and forecasting APIs, native Atlas MCP tools, and paired Workforce REST/MCP contracts. Use the published AionCX contracts for the task you are building. Each surface documents its credential, workspace selector, inputs, results, and recovery behavior. | Surface | Start here | Credential | | - | - | - | | Mach-1 conversations | [Conversation REST specification](/api-reference/mach1/openapi.json) | Scoped `atlas_ingest_` key | | Mach-1 forecasting | [Forecasting REST API](/api-reference/forecasting/overview) | Scoped key with forecast read/submit | | Mach-1 agent operations | [Agent quickstart](/agents/quickstart) | The corresponding scoped key | | Atlas workforce setup, staffing, drafts, and supported publication | [Workforce contract](/api-reference/workforce/overview) | `atlas_mcp_` connection, including explicit REST access for REST calls | | Native Atlas MCP | [Tools and connections](/integrations/mcp) | `atlas_mcp_` connection with domain grants | ## First useful request Start with [transcription](/quickstart), [analysis of an existing transcript](/mach1/analysis), or [a numerical forecast](/mach1/forecasting). Use the [Workforce operator journey](/atlas/resource-management) when implementing its equivalent external operations. ## Authentication and lifecycle Read [authentication](/api-reference/authentication) before implementing a client. A browser session and a scoped bearer key have different purposes. Keep the endpoint and workspace selector from the relevant contract. Asynchronous acceptance establishes that work was admitted. Read the saved status and results to determine completion. Retain operation keys across uncertain retries and follow response pagination. [Callbacks and status](/integrations/webhooks) explains available delivery paths. [Usage and pricing](/mach1/usage) describes the charging basis. Each contract states its supported limits. # Preflight or verify exact retained setup selections Source: https://docs.aioncx.com/api-reference/preflight-or-verify-exact-retained-setup-selections /api-reference/workforce/openapi.json post /api/v1/workforce/setup/check Read-only. Preflight requires the current completed assessment and write grants; verification can recover old committed selections. Each check returns a current native record comparison. No Actor or receipt is created. # Publish an authorized forecast configuration Source: https://docs.aioncx.com/api-reference/publish-an-authorized-forecast-configuration /api-reference/workforce/openapi.json post /api/v1/workforce/forecast-groups Requires mcp:schedules:write and the explicit mcp:schedules:publish grant, plus the issuer’s current native and referenced-source authority. The same grant is rechecked when a saved setup assessment publishes a forecast configuration. # Read an owned retained assessment and its source-authorized conversation Source: https://docs.aioncx.com/api-reference/read-an-owned-retained-assessment-and-its-source-authorized-conversation /api-reference/workforce/openapi.json get /api/v1/workforce/setup/assessment Current Person authority and source permissions are rechecked. resultRef selects a retained revision; after is a history cursor, not an evidence timestamp. Historical revisions are read-only. Missing source access hides the affected analysis. The token owner selects only their own conversation in the granted workspace. External source-domain grants remain necessary for provider, prediction and semantic evidence. At most 200 unique source checks and a 20-second cooperative budget; capped reads fail explicitly. Use view=summary for polling. Running summaries contain operational metadata only; completed summaries project the selected result and its dependencies, without replaying the entire conversation. # Read compatible coverage evidence Source: https://docs.aioncx.com/api-reference/read-compatible-coverage-evidence /api-reference/workforce/openapi.json get /api/v1/workforce/scheduling-groups/{groupId}/coverage Read coverage evidence for a scheduling group over the requested date range. # Read native schedule and activities Source: https://docs.aioncx.com/api-reference/read-native-schedule-and-activities /api-reference/workforce/openapi.json get /api/v1/workforce/schedules/{scheduleId} Read a saved native schedule and its activities. # Read native workforce intraday activity and provisional interval actuals Source: https://docs.aioncx.com/api-reference/read-native-workforce-intraday-activity-and-provisional-interval-actuals /api-reference/workforce/openapi.json get /api/v1/workforce/scheduling-groups/{groupId}/intraday Requires the existing workforce workspace grant, current manage_schedules transport authority, and native view_workforce_actual_activity capability. Returns the native scheduling-group intraday contract, with published schedule, canonical activity, adherence and observed interval facts. Raw provider fields additionally require view_workforce_activity_raw. Active interval actuals are provisional, and unknown source completeness is explicit. # Read retained forecast status and results Source: https://docs.aioncx.com/api-reference/read-retained-forecast-status-and-results /api-reference/forecasting/openapi.json get /api/forecasts/{runId} Requires forecast:read and current source access. Follow next_cursor with the same quantile selection. Reads do not create another prediction run. # Read staffing requirement evidence Source: https://docs.aioncx.com/api-reference/read-staffing-requirement-evidence /api-reference/workforce/openapi.json get /api/v1/workforce/scheduling-groups/{groupId}/requirements Read staffing requirement evidence for a scheduling group over the requested date range. # Recover a native configuration result Source: https://docs.aioncx.com/api-reference/recover-a-native-configuration-result /api-reference/workforce/openapi.json get /api/v1/workforce/configuration-results/{requestKey} Read-only lookup for this token Actor. Null is no confirmed result, not proof that a concurrent request failed. Does not create an Actor. A database/read failure is unknown and returns 503. # Submit a numerical or registered-metric forecast Source: https://docs.aioncx.com/api-reference/submit-a-numerical-or-registered-metric-forecast /api-reference/forecasting/openapi.json post /api/forecasts Requires forecast:submit. Retain the original payload and Idempotency-Key for uncertain retries. Request body limit: 1 MiB. # Validate proposed setup without configuration effects Source: https://docs.aioncx.com/api-reference/validate-proposed-setup-without-configuration-effects /api-reference/workforce/openapi.json post /api/v1/workforce/setup/preview At most 20 recommendations and 100 total members; bounded admission and a 20-second cooperative computation budget. Native validation determines createReady. Operational readiness remains not_verified. Returned commands and retry keys must be retained. forecastGroupKey links a scheduling recommendation to the exact reviewed forecast publication. # Workforce staffing to draft Source: https://docs.aioncx.com/api-reference/workforce/overview The same native workforce operations through REST and MCP. The workforce contract exposes read-only discovery, configuration evidence, staffing calculations and source-fenced draft requests. See the [OpenAPI 3.1 specification](/api-reference/workforce/openapi.json). Release requires both transports together. A handler unit test does not prove external accessibility. ## Discover before configuring `GET /api/v1/workforce/discovery` and the MCP tool `atlas_discover_workforce` call the same native read. Supply `from`, `to` and `as_of` ISO instants; the observation window is at most 31 elapsed days. `view=summary` returns exact Queue, Agent-slot and membership counts plus source states and unresolved decisions. `view=queues` or `view=people` returns at most 100 detail records using `offset` and `limit`; optional `search` filters by display name after Atlas count-checks the complete canonical population. An incomplete read returns a failure rather than a partial inventory labeled complete. The source facts distinguish configured routing membership, opt-in, provider team, supervisor and skill evidence, observed handling, derived presence, provider service-goal assertions and approved Atlas policy. Supervisor assignments do not grant Atlas roles; skill IDs remain provider routing evidence and never grant Atlas Work Qualification. A missing skill snapshot is unknown, not an empty skill set. An exactly identified Queue may show its observed offered-work total, but that aggregate does not prove interval completeness or forecast readiness. Provider business-hours and closure references do not prove the full dated calendar definition. A newer provider hours notice marks an older adopted Atlas calendar as stale; preview and confirm the native calendar update through the existing importer. Missing activity mappings or Person links remain unavailable/unresolved. This operation creates no WFM configuration. Provider identity, semantic demand and Person detail require their separate token grants and current native authority; a workforce grant alone does not expose those sections. ```bash theme={"system"} curl --fail-with-body "$ATLAS_URL/api/v1/workforce/discovery?from=2026-10-01T00%3A00%3A00Z&to=2026-10-25T00%3A00%3A00Z&as_of=2026-10-25T00%3A00%3A00Z&view=summary" \ -H "Authorization: Bearer $ATLAS_TOKEN" -H "X-Workspace-Id: $WORKSPACE_ID" ``` Discover the MCP tool with `tools/list`, then invoke it on `/api/mcp` with the same token's MCP transport grant: ```json theme={"system"} {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}} {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"atlas_discover_workforce","arguments":{"workspace_id":"","from":"2026-10-01T00:00:00Z","to":"2026-10-25T00:00:00Z","as_of":"2026-10-25T00:00:00Z","view":"summary"}}} ``` Missing `api:connect` or current schedule authority is a 403 REST error. An archived activity source is an explicit unavailable section rather than zero presence. A changing or capped inventory fails the read; retry after source stabilization. REST errors use `{error:{code,message}}`, and MCP returns the same code in a structured tool failure. ## Review and configure a workforce Admin → Workspace setup → Workforce setup begins with this deterministic discovery. The existing Atlas native agent must read the same inventory before preparing a setup plan. It may inspect only a named gap, then submits the existing structured preview with supported changes or exact blockers. The discovery read does not create a group or publish a schedule. Existing saved setup plans remain readable under current source permissions. Applications and external agents can perform the same setup through `POST /api/v1/workforce/setup/preview` / `atlas_preview_workforce_setup`, forecast-group publication, scheduling-group creation and dated membership creation. Each mutation rechecks current native authority and attributes its effect to the token Actor. Forecast-group publication additionally requires `mcp:schedules:publish` alongside `mcp:schedules:write`, including when invoked through saved-assessment apply; the native transaction rechecks the stored grant. No new credential, setup ledger or agent runtime is required. Preview accepts at most 20 recommendations and 100 total proposed members, under shared compute admission. A forecast configuration always requires `horizonDays`, even when `demand` is null. Targets must match the exact work scope, reporting timezone and effective period. A scheduling recommendation may name another recommendation's `forecastGroupKey`; its returned command binds that exact forecast publication. Apply the forecast first. A queue is not required to belong to exactly one forecast group. Retain the returned commands, including their keys and source fingerprints. Group creation links the group and native object in one transaction. Membership creation provisions any needed native Agent slot in the same transaction as its dated membership; an assignment/FTE/overlap failure leaves neither partial effect. Existing overlapping membership is refused, not silently edited. Assignment enforce mode cannot be bypassed with a Person-only request. When a reused Agent occupancy is employment-linked, membership must explicitly name that employment assignment, including in a legacy workspace. A Person-only request returns `workforce.member_assignment_required` (422) instead of losing the assignment context and leaving a roster that cannot commit shifts. Inspect the effective assignment and submit a new reviewed request. `createReady` describes configuration validation. `operationalReadiness: not_verified` remains until source, qualified roster, demand and draft checks succeed. Membership eligibility is rechecked at commit. Successful configuration does not claim a forecast, executable schedule, customer activation or later service improvement. For an assessment saved by the native agent, `POST /api/v1/workforce/setup/apply` / `atlas_apply_workforce_setup` selects only `{sessionId, resultRef, key, memberRequestKey?}`. The backend loads the exact saved command; callers cannot replace its configuration. A new correction prevents uncommitted effects from the old result. Already committed requests remain recoverable using the original selector and current authority. Each item is an independent authorized effect, so partial completion is explicit. The requested historical window is retained as `{start, end, timezone}` and is limited to 366 elapsed days. It does not imply complete observations or change a source's grain. The setup page issues the assessment through the existing Agent Kernel with reads only, retains corrections in that conversation, and lets the operator reopen their saved work. `GET /api/v1/workforce/setup/assessments` / `atlas_list_workforce_assessments` lists at most ten of the issuing Person's own sessions executing in the selected workspace; it returns no conversation history or titles from other workspaces. External agents can independently discover sources, invoke the same native preview and apply its exact commands through the paired REST/MCP operations. Use `GET /api/v1/workforce/configuration-results/{requestKey}?kind=group|member|forecast_group` or `atlas_inspect_workforce_configuration` after uncertainty. A saved receipt confirms the native effect. A failed read leaves the outcome unknown; a null response is no confirmed receipt and does not prove an in-flight request failed. Reuse the original key rather than create another. An unrelated same-name group is never treated as a successful retry. ### External creation and recovery example In an authorized test workspace, retain one UUID in `REQUEST_KEY`. The connection needs explicit `api:connect`, workspace scheduling write scope and the issuer's current `manage_schedules` capability. Membership additionally requires `manage_workforce_roster`. ```bash theme={"system"} curl "$ATLAS_URL/api/v1/workforce/scheduling-groups" \ -H "Authorization: Bearer $ATLAS_TOKEN" -H "X-Workspace-Id: $ATLAS_WORKSPACE_ID" \ -H "Idempotency-Key: $REQUEST_KEY" -H 'Content-Type: application/json' \ --data '{"name":"Reviewed support roster","timezone":"America/Chicago","operating_open":"08:00","operating_close":"17:00"}' curl "$ATLAS_URL/api/v1/workforce/configuration-results/$REQUEST_KEY?kind=group" \ -H "Authorization: Bearer $ATLAS_TOKEN" -H "X-Workspace-Id: $ATLAS_WORKSPACE_ID" ``` Using the same connection and UUID, an MCP client discovers and invokes: ```json theme={"system"} {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}} {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"atlas_create_schedule_group","arguments":{"workspace_id":"","request_key":"","name":"Reviewed support roster","timezone":"America/Chicago","operating_open":"08:00","operating_close":"17:00"}}} {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"atlas_inspect_workforce_configuration","arguments":{"workspace_id":"","request_key":"","kind":"group"}}} ``` Send these to `/api/mcp` with the bearer credential, `Accept: application/json, text/event-stream` and the negotiated MCP protocol version. A changed body under the same key returns `workforce.operation_conflict`. A superseded review returns `workforce.assessment_superseded`. Missing transport or current native grants return 403; unavailable commit/read acknowledgement returns an unknown outcome (503). No browser cookies are used. Older MCP group/member argument forms remain accepted, but callers must supply or retain the returned request key for safe recovery. ## Credentials In Settings → MCP connections, create an integration with explicit REST access. REST requires `api:connect` on the existing `atlas_mcp_` connection. Existing keys gain no implicit REST permission. Scheduling reads require workforce workspace grants and current `manage_schedules` authority; effects also require the workforce write grant. Provider reads retain separate provider grants and current provider setup authority. Explicit integrations default to 90 days. A narrowly scoped single-workspace planning connection can explicitly expire only when revoked. Ordinary MCP defaults remain seven days. Rotation shows the new secret once and atomically revokes its predecessor. Both transports recheck current issuer authority and attribute effects to the token Actor. Browser cookies, caller identity fields, and `atlas_ingest_` scheduling credentials are refused. OAuth is not implemented by this contract. Renewable integrations can explicitly include `mcp:schedules:publish` for reviewed forecast-group publication and `mcp:semantic:read` with its workspace selector for setup evidence. These grants are not implicit, and current native authority is checked on creation, rotation and invocation. Until-revoked planning keys exclude both grants; use a renewable connection when setup needs them. Complete or reconcile pending issued draft requests before rotating a connection. The successor has its own token Actor and cannot inspect or commit requests issued by the revoked predecessor; existing source receipts remain available to authorized native users. ## Source and calculation contract 1. Read `/api/v1/workforce/discovery` / `atlas_discover_workforce`, then `/readiness` if configuration-only evidence is needed. Exact counts distinguish empty configuration from failed reads. `queue_settings` now pages all active queues and preserves provider service-goal units and dates. Missing, conflicting, sensitive or unavailable values are not defaults. These settings are configuration evidence, not observed performance or proof of current provider delivery. Provider discovery and sync receipts retain their separate grants. 2. Inspect `/connections`, inventory, sync status and calendar preparation. These reuse existing provider operations. Retained inventory alone does not prove current delivery; missing receipts remain unknown. 3. Inspect `/scheduling-groups` and `/scheduling-groups/{groupId}`. Confirm the existing dated roster, calendar and demand configuration. This API does not guess assignments or silently configure customer workspaces. 4. Read or compute requirements, then issue, inspect and commit a native draft request. Staffing compute uses authored manual demand or completed forecast evidence. It does not run potentially long inference inside the WFM request. Missing evidence returns `prediction_not_ready` with a next action; obtain completed evidence through the existing forecast workflow before retrying. `residual_unplanned_shrinkage` is an explicit fraction from zero up to, but excluding, one. It is the loss remaining after scheduled nonproductive activities. Zero explicitly assumes no additional unplanned loss; it is not inferred from total shrinkage. New calculations retain exact net demand beside existing gross requirements. Productive coverage compares productive supply adjusted by residual loss with exact net demand over UTC event boundaries. Historical gross rows remain readable, but absent net evidence or an unassessed residual is unavailable for productive coverage decisions. Native callers that omit residual retain exact net without silently choosing zero; a recomputation with an explicitly assessed residual is required for coverage-backed leave approval. Missing-only evidence is reported as `state: "unknown"`, `assessment: "not_assessed"`, with null demand facts. Automatic approval remains blocked. An authorized human manager may use the existing native manual override with a reason; the receipt retains that coverage was not assessed. Invalid or stale evidence and unavailable qualification remain blocked. Rounded gross counts cannot reconstruct net demand. JS and PostgreSQL normalize derived gaps within `1e-9` people of zero to zero, keeping source evidence unrounded. The generator remains a bounded heuristic over gross presence and labels productive coverage as not evaluated by that optimizer; it does not optimize activity placement or prove global infeasibility. ## REST example Read the native Intraday snapshot with `GET /api/v1/workforce/scheduling-groups/{groupId}/intraday?date=YYYY-MM-DD` or MCP `atlas_get_workforce_intraday` with `workspace_id`, `group_id` and optional `date`. The date defaults to the scheduling group's local today. Both use the same `IntradayService` and snake-case response as the native board, including published schedule references, canonical activity, adherence, interval observation metadata and forecast/actual comparisons. The existing workforce workspace grant and current transport authority apply; the issuer must additionally have `view_workforce_actual_activity`. Raw provider status and substatus require `view_workforce_activity_raw`. `intervals[].observation` separates elapsed and remaining interval time, source observation and stabilization cutoffs, and provisional/final person-time status. `forecast_actuals` retains the forecast's original interval grain and timezone. Its full-interval forecast and actual so far are separate values; the live read never writes or finalizes prediction actuals. Unknown source completeness remains explicit. Use `history=deferred` in REST or `include_history=false` in MCP for the native deferred-history mode. Existing refresh requests see newly ingested facts without initiating a provider collection. Use actual authorized identifiers and retain UUID operation keys before sending. Environment variables below keep credentials out of command literals. ```bash theme={"system"} curl --fail-with-body "$ATLAS_URL/api/v1/workforce/readiness" \ -H "Authorization: Bearer $ATLAS_TOKEN" \ -H "X-Workspace-Id: $WORKSPACE_ID" ``` Compute staffing with `POST /api/v1/workforce/scheduling-groups/{groupId}/requirements/compute`, the same bearer/workspace headers, `Content-Type: application/json`, and `Idempotency-Key: `: ```json theme={"system"} {"from":"2026-11-02","to":"2026-11-03","requested_at":"2026-10-22T23:00:00Z","residual_unplanned_shrinkage":0} ``` Use the retained current request timestamp. This persists latest staffing evidence; it is not an exactly-once staffing receipt or a schedule commitment. After uncertainty, inspect saved evidence before recomputing. Read-only `POST /requirements/evaluate` takes the date range and residual fraction but neither starts inference nor persists requirements. Issue with `POST /api/v1/workforce/draft-requests`, a new retained `Idempotency-Key`, and: ```json theme={"system"} {"target":{"group_id":"22222222-2222-4222-8222-222222222222","period_start":"2026-11-02","period_end":"2026-11-03"}} ``` Issue saves native proposal/source evidence and creates no shifts. Inspect `GET /draft-requests/{requestKey}` before `POST /draft-requests/{requestKey}/commit` with the same `Idempotency-Key` and no body. Commit rechecks current authority and source revisions, then creates a draft; publication remains separate. Identical retries through either transport return the native receipt. After a stale-source conflict, obtain and review a new proposal. The setup page continues from verified scheduling configuration into these same operations. A scheduling recommendation can retain `review.planning` with `{from,to,timezone,residualUnplannedShrinkage,basis,evidenceRefs}`. It requires 1–14 inclusive dates, the scheduling group's timezone, a residual fraction in `[0,1)`, an explanation and retained source references. The native agent validates its cited references. Both external setup preview and assessment reads use the same additive contract. Proposed inputs are analysis, not a new source authority or permission to commit. The draft form uses those proposed inputs without asking the operator to reconstruct them. Missing planning evidence blocks the initial calculation and links back to Atlas; an operator may explicitly enter their own inputs. Calculate staffing, review the proposed shifts, then commit. The page retains operation keys across reloads in the current browser tab and rereads the current draft against the receipt and reviewed shifts. A lost response remains recoverable using the original key. An empty proposal is not a completed first draft. Unconfigured demand returns `generation.demand_unavailable`; this operation does not substitute minimum-floor staffing. Signed-in operators and outside clients share the workspace compute limit, while retaining distinct human and token Actors. ## MCP example MCP requires `mcp:connect` and native domain grants independently of REST. Send JSON to `/api/mcp`: ```bash theme={"system"} curl --fail-with-body "$ATLAS_URL/api/mcp" \ -H "Authorization: Bearer $ATLAS_TOKEN" \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-06-18' \ --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' ``` ```json theme={"system"} {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"atlas_inspect_staffing_requirements","arguments":{"workspace_id":"11111111-1111-4111-8111-111111111111","group_id":"22222222-2222-4222-8222-222222222222","from":"2026-11-02","to":"2026-11-03"}}} ``` Use actual granted IDs. Draft tools are `atlas_issue_draft_schedule`, `atlas_inspect_draft_schedule`, and `atlas_commit_draft_schedule`. Their `request_key` equals the REST `Idempotency-Key`. Tools must be visible under real current grants; registration alone is insufficient. ## Limits, failures and verification Requests are bounded to 64 KiB, 14 inclusive dates and 200 roster entries for generation. Heavy calls share one active operation per workspace and token, a 30-second cooperative budget, 10-second database requests and a 45-second deadline across database pages. Admission leases expire after 120 seconds if their completion acknowledgement is lost. They are operational telemetry, not effect receipts; read-only calculations do not write schedule or requirement records. REST errors use `{ "error": { "code": "generation.source_changed", "message": "generation source changed" } }`. Newly exposed MCP operations return the same actionable structured code. Cases include expired/invalid bearer (401), missing REST or current native grant (403), source/revision conflict (409), invalid input (422), compute concurrency (429), and unavailable evidence (503). A timeout at commit is an unknown outcome: inspect and reuse the same native draft key. Run `scripts/workforce/smoke-external.mjs` against an authorized deployment to exercise real HTTP REST and MCP without cookies or service-role credentials. Full source-to-draft and live customer activation require separately retained acceptance evidence. Confirmed command success does not establish later service improvement. ## Review, preflight and verification `GET /api/v1/workforce/setup/assessment` and `atlas_read_workforce_assessment` read an owned assessment, its retained revisions and currently authorized conversation. `sessionId` is required; `resultRef` selects an earlier revision. `after` is an optional history cursor. The original `{start,end,timezone}` remains unchanged during corrections. The current source permission checks also apply to older derived analysis. External provider, prediction and semantic evidence additionally requires the connection’s corresponding domain grant; workforce read never inherits those grants from its owner. `assessmentAvailability` explicitly distinguishes available, pending, wrong-workspace and unavailable evidence, with an actionable reason for unavailable saved analysis. History reads admit at most 200 distinct source checks with a 20-second cooperative budget; a capped read returns `workforce.budget_exceeded`, never an empty success. No caller user ID, browser session or substituted workspace identity is accepted. Review details include cited queue/Person tables, assumptions, reused inputs, decisions, and separate staffing/evidence issues. They are analysis, not an eligibility grant. Native preview computes `createReady`; `operationalReadiness: "not_verified"` remains separate. An unavailable historical count is not an observed zero. `POST /api/v1/workforce/setup/check` and `atlas_check_workforce_setup` accept the same saved selector plus `keys` and `mode`. `preflight` rechecks current authority, source fingerprints and selected native inputs; it requires a current completed assessment and the effect's write/publication grants. `verify` is read-only and does not provision an Actor. It compares the original request with the current saved group/publication or membership. Native commit repeats source, revision, assignment-span, overlap and FTE validation; preflight does not reserve capacity or promise a later commit. ```bash theme={"system"} curl --fail-with-body --get "$ATLAS_URL/api/v1/workforce/setup/assessment" \ -H "Authorization: Bearer $ATLAS_TOKEN" \ -H "X-Workspace-Id: $WORKSPACE_ID" \ --data-urlencode "sessionId=$SESSION_ID" # setup-check.json contains the exact retained sessionId/resultRef and selected keys: # {"sessionId":"...","resultRef":"...","keys":["forecast","roster"],"mode":"preflight"} curl --fail-with-body "$ATLAS_URL/api/v1/workforce/setup/check" \ -H "Authorization: Bearer $ATLAS_TOKEN" \ -H "X-Workspace-Id: $WORKSPACE_ID" \ -H "Content-Type: application/json" --data-binary @setup-check.json ``` MCP discovery and invocation use the same external credential after initialization: ```json theme={"system"} {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}} {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"atlas_read_workforce_assessment","arguments":{"workspace_id":"WORKSPACE_UUID","sessionId":"SESSION_UUID"}}} {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"atlas_check_workforce_setup","arguments":{"workspace_id":"WORKSPACE_UUID","sessionId":"SESSION_UUID","resultRef":"RETAINED_RESULT_REF","keys":["roster"],"mode":"verify"}}} ``` Apply dependencies in order: forecast publication, linked scheduling group, then dated memberships. Each item is one native transaction. Stop dependent effects until the parent is `verified`; separate successful effects remain committed after a later failure. If a response is lost, verify the original selector before retrying the same command. `not_confirmed` means no effect was found for that issuer/key; `unknown` means the read could not establish an outcome; `changed` means the saved current record differs from the review. Neither is an applied-and-verified success. Human and token Actors retain their existing distinct command ownership; REST/MCP replay uses the same token. A superseded preflight returns 409 `workforce.assessment_superseded`; invalid or duplicate selection keys return 422; revoked domain authority returns 403; admission contention returns 429 `workforce.compute_busy`. A per-item `blocked` source check explains why no apply should start. Structured MCP failures retain the same actionable code. A verified configuration is not a demand-backed draft, provider activation or evidence of improved service. Those subsequent operations retain their own native checks. ## Setup progress and run deletion Use `view=summary` with the existing assessment read operation to poll progress. It returns four plain-language sections and the run's state. While a run is active, it does not hydrate the conversation or repeat source queries. Once complete, it loads the selected plan with the same current source permission checks. `checked` means a request returned; the plan establishes which evidence is usable. Full source-authorized history remains available with `view=history` (the default). The assessment list includes `needsAttention` metadata. A run can complete with blockers or an inspection-limit failure; these display as “Needs attention”. Completion and this summary flag do not establish scheduling readiness. Open the result for its currently authorized findings. ```bash theme={"system"} curl --fail-with-body --get "$ATLAS_URL/api/v1/workforce/setup/assessment" \ -H "Authorization: Bearer $ATLAS_TOKEN" \ -H "X-Workspace-Id: $WORKSPACE_ID" \ --data-urlencode "sessionId=$SESSION_ID" --data-urlencode 'view=summary' curl --fail-with-body -X DELETE \ "$ATLAS_URL/api/v1/workforce/setup/assessment?sessionId=$SESSION_ID" \ -H "Authorization: Bearer $ATLAS_TOKEN" \ -H "X-Workspace-Id: $WORKSPACE_ID" ``` The same read and delete are discoverable through MCP: ```json theme={"system"} {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"atlas_read_workforce_assessment","arguments":{"workspace_id":"WORKSPACE_UUID","sessionId":"SESSION_UUID","view":"summary"}}} {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"atlas_delete_workforce_assessment","arguments":{"workspace_id":"WORKSPACE_UUID","sessionId":"SESSION_UUID"}}} ``` Deletion requires workforce write and the owner's current `manage_schedules` authority. It closes only that Person's setup run and records the acting Actor. It preserves saved groups, schedules and native command receipts. A running lease or temporary storage outage returns `{deleted:false,cleanupPending:true}`; the run is hidden immediately and existing native cleanup retries its removal. Absent and foreign runs both return `{deleted:true,cleanupPending:false}`. Missing write grants return 403; extra identity fields are invalid input. The setup agent uses the same native kernel with a focused read/plan tool set. It stops source discovery after twelve steps and finishes by sixteen, retaining a native plan or an explicit implementation blocker. Invalid read arguments do not erase subsequent corrections. Fixed tool diagnostics distinguish malformed input (`invalid_tool_input`), an operation outside the agent's configuration (`operation_not_configured`) and unusable evidence (`citation_unavailable`). They contain no source contents and do not authorize access to cited results. These bounds do not turn an unavailable source, blocked plan or empty proposal into a completed first draft. # Start using Atlas Source: https://docs.aioncx.com/atlas/get-started Choose your workspace, find the tools available to your role, and complete your first Atlas task. Start Atlas by confirming your workspace and choosing the operational result you need. You can begin with one Agency and expand as your work requires. ## 1. Confirm your access Sign in through your organization's Atlas link. Complete any account verification or invitation steps, then check the workspace switcher in the top bar. Your organization membership, workspace access, and task permissions determine what you can read or change. A connected agent record and a person's login access are separate. Ask your administrator to check both when someone is missing from a roster or cannot sign in. ## 2. Find your work | You want to | Open | | - | - | | Review a call or transcript | Conversations | | Review assigned quality work | Quality → My reviews | | Plan staffing or schedules | Workforce → Planning | | See your schedule or request leave | Workforce → My schedule or Time off | | Edit knowledge | Knowledge → Knowledge workspace | | Find assigned follow-up | Work → My work | | Configure a source, calendar, or role | Admin Center | Use **Search Atlas** with Command K or Control K to find a page. Open the Atlas agent from the top bar when it is enabled for your workspace. Describe the result you need and the scope, such as the team and dates. ## 3. Check the data behind the task Before acting, confirm the workspace, time period, and source. A saved connection or an entry in an inventory establishes configuration; current sync evidence and actual observations establish what data is available. For workforce planning, check the roster, operating calendar, and demand history. For quality work, check the interaction, transcript, evaluation version, and evidence. For knowledge, check the article version and publication state. ## 4. Complete a task > **[Prepare a staffing plan](/atlas/resource-management)** > > Review demand, roster, requirements, and a draft schedule. > **[Review an interaction](/atlas/review-interactions)** > > Follow a finding or evaluation back to its source. > **[Publish knowledge](/atlas/knowledge-operations)** > > Save, review, approve, and publish an article. > **[Connect an external agent](/agents/quickstart)** > > Use the existing external connection and its granted operations. ## If something is unavailable Check the selected workspace first. Ask an administrator to verify the relevant permission or enabled feature. For a missing source or result, retain the record or request ID, the time window, and the displayed status when asking for help. An empty result, an unavailable read, and work still in progress have different meanings. Follow the displayed recovery action before submitting the same work again. # Edit, review, and publish knowledge Source: https://docs.aioncx.com/atlas/knowledge-operations Maintain knowledge articles in Atlas, review changes, publish approved versions, and inspect supported delivery results. Knowledge Operations keeps the answers used in customer operations current. The Knowledge workspace brings article authoring, source documents, media, review states, and supported delivery destinations together. ## Before you start Open **Knowledge → Knowledge workspace**. Article and destination work uses content-management permissions; documents and media have their own source-management permissions. Confirm the workspace, article, and version you intend to change. ## 1. Find or create an article Use **Articles** to open an existing article or begin one. Review the current published text, available source material, and any unpublished changes. Documents and Media contain source assets and recordings. Their availability and extraction states are separate from an article's approval and publication. ## 2. Write and inspect the changes Use the visual editor or Markdown view. Add the relevant sources and supported attachments, then use **Preview** to inspect the reader view. Use **Changes** to compare the article body with the version you opened. Save explicitly. If a version conflict occurs, retain your changes and review the newer saved version before trying again. ## 3. Review, approve, and publish Move the saved article through its available review and approval actions, then publish the intended version. The **Needs attention** view shows articles waiting for review or approval and failed source assets. These states describe the content's workflow; they are separate from an assigned Inbox task. Check the saved article state after each action. An approved draft and a published reader version have different purposes. ## 4. Inspect output and delivery Open the article's compiled outputs and delivery history. Select only a supported destination and a successfully validated output. Atlas, export, and supported Zoom knowledge-base destinations can use label-driven delivery. Destination setup and access determine what is available. Other external systems require their own supported adapter. Inspect the recorded delivery outcome. A failed delivery remains failed even if the HTTP request that created its record succeeded. ## Maintain the article Return to the same article for subsequent changes so its versions and history stay connected. Check source changes, pending reviews, output validation, and delivery failures. A recorded delivery attempt establishes what happened at that time. Check the destination when you need to confirm its current content. # Atlas and the five Agencies Source: https://docs.aioncx.com/atlas/overview Find the Atlas workflows for staffing, quality, customer intelligence, workforce development, and knowledge operations. Atlas brings the work of running customer operations into one platform. Its five Agencies describe the operational jobs; the application groups the screens you use under Workforce, Quality, Conversations, Analytics, Knowledge, and Work. | Agency | What you use it for | Where to begin | | - | - | - | | Resource Management | Forecast demand, calculate staffing, prepare schedules, and compare delivery with the plan | [Prepare a staffing plan](/atlas/resource-management) | | Performance Assurance | Review evaluations and their supporting conversations, then address issues | [Review interactions and evidence](/atlas/review-interactions) | | Customer Intelligence | Examine contact reasons, scenarios, repeat interactions, and customer needs | [Inspect findings and source evidence](/atlas/review-interactions#inspect-findings) | | Workforce Development | Use observed performance and relevant knowledge to support coaching and onboarding | Begin with an evidenced need, the relevant knowledge, and assigned follow-up in Work | | Knowledge Operations | Maintain articles, reviews, published versions, and supported delivery destinations | [Edit and publish knowledge](/atlas/knowledge-operations) | ## Find the right screen Select a product in the left rail to see its pages. Use **Search Atlas** with Command K or Control K to find a destination. **Admin Center** contains workspace configuration, access, integrations, calendars, and other administration. Your role and enabled workspace features determine what appears. Ask a workspace administrator for the specific task you need to perform if a page is unavailable. Switching workspace changes the data and configuration you are working with. ## Work from evidence A finding describes what was observed in a source. An evaluation applies a particular form or Definition. A forecast predicts a particular metric over a time window. Open the source, scope, version, and status before using any of these to make a decision. For example, a reported promise to call a customer on Friday is evidence of a commitment. Confirm its later completion through the relevant operational record. ## First task Choose one result to produce: a reviewed conversation, a staffing plan, or an approved article. Follow that guide through its final saved state. You can then connect related work through the same workspace. Developers and external agents can use the [published API and MCP interfaces](/api-reference/overview) for the operations covered by those contracts. # Prepare a staffing plan and schedule Source: https://docs.aioncx.com/atlas/resource-management Review workforce configuration, forecast demand, calculate requirements, generate a draft, and publish a reviewed Atlas schedule. Resource Management connects the demand you expect with the people and working time available to meet it. This guide takes a planner from existing source data and workforce configuration to a reviewed schedule. ## Before you start Confirm the workspace and reporting timezone. You need schedule-management access, workforce-roster access for membership changes, prediction access to run forecasts, and the applicable publication permission. Have the following available: * The work scope and observed history you want to forecast. * Operating hours, holidays, and closures. * People, effective employment assignments where required, and dated group membership. * Service targets and explicit staffing assumptions. If configuration is missing, open **Admin Center → Workspace setup → Workforce setup**. Review the discovered evidence and proposed setup before applying its supported changes. An imported queue or agent record alone does not establish a complete, current planning setup. ## 1. Review the planning scope Open **Workforce → Planning → Forecast groups**. Confirm the exact work being forecast, its timezone, service targets, forecast configuration, and effective version. Open **Scheduling groups** and check the people, operating calendar, and demand configuration. Keep team reporting, forecast scope, and scheduling membership distinct. For a new setup, resolve missing evidence or configuration before treating the group as ready for operational use. ## 2. Obtain completed demand evidence For a forecast group configured to use predictions, select **Run forecast**. Follow **Open forecast** to inspect progress and the completed run. Review the metric, history window, interval, forecast horizon, and data coverage. A queued run is still processing. Missing history needs investigation before it becomes a staffing assumption. A group using authored manual demand follows its configured manual inputs instead. See the [glossary](/reference/metrics-and-terms) for the distinction between demand and a forecast. ## 3. Review staffing requirements Inspect the scheduling group's demand and requirements for the planning dates. Check service assumptions and residual unplanned shrinkage. Use an explicit residual loss assumption after accounting for scheduled meals, breaks, and other nonproductive time. Review net demand and gross requirements at matching intervals. If requirements report that prediction evidence is not ready, finish or select the relevant forecast before retrying. Staffing calculation does not start a separate long forecast inside the request. ## 4. Prepare a draft schedule Open **Workforce → Schedules**, select the group and period, and create a draft. Use **Generate shifts** when generation is available. Inspect the proposed shifts, rule results, and remaining deficits before applying the proposal. Review each person's eligibility and work-rule results, then place or check breaks and other activities. Generation uses a bounded heuristic over staffing requirements. The proposal can leave gaps. Its presence summary does not establish that activity placement has achieved productive coverage. ## 5. Review and publish Check the saved draft, dates, timezone, people, activities, and unresolved warnings. The publication dialog distinguishes **Ready to publish**, **Publish with acknowledgment**, and **Resolve before publishing**. A permitted publication makes the schedule available to employees. Follow the returned state if an approval is required. Verify the final saved publication rather than relying on a clicked button. After publication, use **Intraday** and **Staffing calendar** to compare the plan with observed delivery. ## If the workflow stops | What you see | Next action | | - | - | | Forecast queued or prediction not ready | Open the retained forecast and wait for or resolve its result | | Missing or incomplete source evidence | Check the connection, observed history, and sync evidence | | Missing person or ineligible membership | Check the Person, effective assignment, and dated roster | | Source or revision changed | Reopen the relevant evidence and review a fresh proposal | | Commit or publish timed out | Inspect the existing request and saved state; recover with the original key | Applications and external agents can use the paired [Workforce REST and MCP operations](/api-reference/workforce/overview). They use the same configuration, staffing, draft, and publication rules. # Review interactions and evidence Source: https://docs.aioncx.com/atlas/review-interactions Inspect conversation findings, source passages, and quality evaluations in Atlas before taking action. Use Atlas to review what happened in a conversation and the evidence supporting a finding or evaluation. Performance Assurance and Customer Intelligence use the same underlying interactions, with different questions and criteria. ## Before you start Select the workspace and time period. You need access to the interaction and the relevant transcript, recording, findings, or evaluation. Recording access is checked separately from the ability to see a general result. ## Open an interaction Find the conversation in **Conversations** or follow the interaction link from a review or finding. Confirm its source identifier and date before interpreting the result. Inspect the available transcript and recording. Speaker labels, timing, and original audio may be absent for a supplied transcript. ## Inspect findings Review the analysis version, processing state, and supporting passage for each relevant finding. A finding can identify a need, scenario, action, or commitment. Distinguish a statement made during the call from independently verified completion afterward. Follow the evidence instead of treating a summary as the full source. Check the input and transcript revision when comparing results or navigating pages. An unavailable analysis, a failed analysis, and a completed analysis with no findings are different states. ## Review quality work Open **Quality → My reviews** for assigned review work, or inspect the relevant evaluation from Quality. Check the evaluation's form or Definition version and criteria. Review field-level evidence and the source interaction before accepting the conclusion. Manual evaluation submission requires the permission to create evaluations; a reader may have access to inspect the workspace without permission to submit a score. Record follow-up in the existing operational workflow for the issue or assigned work. Use the relevant knowledge when coaching or explaining the expected practice. ## Check a trend Open the appropriate Analytics view when you need to compare multiple interactions. Confirm the metric definition, population, time window, and available history. A repeat-contact measure and a verified resolution measure answer different questions. Read the selected metric's definition before calling a result first-contact resolution. For programmatic reads, use the published [Mach-1 results contract](/mach1/results) or the relevant authorized Atlas interface. Browser-session routes and external APIs have distinct credentials. # Changelog Source: https://docs.aioncx.com/changelog Updates to the Atlas developer platform and its contracts. ## October 26, 2026 ### Customer guides and forecasting reference * Added Atlas guides for getting started, workforce planning, interaction review, and knowledge publication. * Put transcription first in the Mach-1 journey and connected analysis, evidence, and forecasting. * Added forecasting REST reference and an agent quickstart using existing scoped interfaces. * Documented current USD 0 forecasting and account-configured credit and top-up amounts. ## October 2026 ### Mach-1 developer access * Added scoped personal keys, direct audio and transcript submission, asynchronous interaction reads, and the nine processing and retrieval tools on Mach-1 MCP. * Added a Build workspace with Sources, Requests, Analysis, Developers, and Usage views. New self-service workspaces receive a pinned starter Interaction findings analysis when the required model is configured. * Added exact interaction and external-conversation identifier search with source provenance. Filtered cursors retain the selected filters. * Added minute-based prepaid transcription and analysis billing, with Stripe top-up fulfillment and funding recovery. Availability depends on the deployment's billing configuration. ## August 2026 ### Provider-auth connection authority * Provider runtime authentication now resolves credentials directly from the active Atlas connection's Vault references. * Removed the retired binding-resolution RPC from the live broker path for Zoom, Vonage, and LinkLive. ## July 2026 ### Developer portal initialized * Added the Atlas v1 developer documentation foundation. * Published the initial object, identity, Lists and Cycles, and semantic-layer concepts. * Added production-readiness guides for domain modeling and integration design. * Established placeholders for the external API, authentication, webhooks, MCP, and future SDKs without implying unreleased contracts. > [!NOTE] > > Future entries will identify contract changes, effective dates, migration steps, and deprecations when applicable. # Identities Source: https://docs.aioncx.com/concepts/identities Resolve source-system keys to durable Atlas records. Identities connect external system records to durable Atlas objects. Examples include CRM IDs, CCaaS agent IDs, HRIS employee numbers, email addresses, and external account IDs. Identity resolution lets Atlas connect operations across systems without treating each provider record as a different business entity. Mappings and lifecycle changes should be auditable. ## Identity tuple Treat an external identity as a scoped tuple: ```text theme={"system"} source system + identifier type + normalized value → object record ``` For each identifier, define: * who issues and owns it; * the object type it can identify; * normalization and case rules; * whether it can be reassigned; * how conflicts are reviewed; * whether it is primary or alternate. ## Resolution principles 1. Prefer immutable provider identifiers over names or labels. 2. Normalize before matching, using a documented rule. 3. Keep raw source values available for traceability where policy allows. 4. Make ambiguous matches reviewable instead of silently choosing a record. 5. Treat merge and split operations as governed lifecycle events. > [!NOTE] > > The external identity write and resolution contracts are not yet published. Use this model to prepare mappings; do not infer an endpoint or payload from the examples. # Lists and Cycles Source: https://docs.aioncx.com/concepts/lists-and-cycles Organize objects into governed collections and staged workflows. **Lists define scope**: a governed set of objects included in work. **Cycles define operating cadence**: when that work repeats, which stages it moves through, and how progress is recorded. Together, Lists and Cycles define who or what is in scope and when the work happens. ## Choose the right shape | Need | Use | | - | - | | A curated or dynamic collection | List | | Ordered work stages | Cycle | | Multiple saved perspectives | List views | | A workflow inside a larger workflow | Nested cycle | Examples include a weekly QA review List, monthly customer intelligence Cycle, payroll lock Cycle, implementation issue List, or content publication Cycle. Entries point to canonical object records. This lets one object participate in multiple workflows while retaining one identity and one governed set of relationships. ## Model transitions explicitly A stage should describe meaningful operating state, not merely a screen column. Define who can move an entry, which transitions are valid, what evidence is required, and what should happen when a cycle rolls over. > [!TIP] > > Keep state that belongs to the workflow on the entry or transition. Keep durable business facts on the underlying object. Lists and Cycles are also an execution surface for agents: an agent can triage, propose movement, or act when its authority grant permits it. # Objects Source: https://docs.aioncx.com/concepts/objects Durable, typed records for the things Atlas knows about. An **object** is a durable business entity represented in Atlas. Examples include a person, organization, account, queue, policy, issue, content item, location, shift, timecard, or interaction. Objects provide stable identity while attributes, relationships, versions, evidence, metrics, access rules, and lifecycle events evolve around them. ## Object anatomy An object is composed from a few distinct concerns: * **Type** — the class of thing the record represents. * **Record** — its durable Atlas identity within a workspace. * **Attributes** — typed facts and descriptive state. * **Identities** — keys that connect records to source systems. * **Relationships** — typed links to other records. * **Governance** — access, lifecycle, and audit controls. Atlas platform artifacts can also participate in the object model. Metrics, insights, dashboards, predictions, decision artifacts, and Lists can be governed and related through the same spine as operational entities. ## Design rules > [!TIP] > > Create an object when the concept needs durable identity, relationships, governance, or workflow participation. > [!WARNING] > > Do not derive identity from a display name. Names are attributes; external keys belong in the identity layer. Avoid creating an object for every event or denormalized warehouse row. Events describe what happened; objects describe what persists. # Atlas primitives Source: https://docs.aioncx.com/concepts/overview The small set of concepts behind Atlas decision intelligence. Atlas is organized around primitives rather than isolated features. Each primitive supplies a stable contract that products, analytics, integrations, and agents can share. | Primitive | Responsibility | | - | - | | Objects | Durable records for operational entities and Atlas artifacts | | Identities | External and alternate keys that resolve to an object | | Relationships | Typed connections between objects | | Data surfaces | Governed access to operational records and projections | | Metrics | Reusable measurements with defined grain and lineage | | Analyses | Decision-oriented interpretation of metrics and evidence | | Lists | Governed collections of object records | | Cycles | Operating cadence, stages, and transition history | | Semantic layer | Shared definitions for fields, metrics, filters, and lineage | | Decision layer | Governed practices, policies, rules, guidance, and outcomes | | Planner, execution, and audit | Governed movement from intent to accountable action | ## From signal to action Data enters Atlas through governed data surfaces. Atlas resolves records to objects, applies semantic meaning, evaluates the relevant operating context, and makes the result available to people, workflows, and agents. This separation matters: a provider payload can change without changing the business identity of an object, and a workflow can change without rewriting the object it contains. > **[Objects](/concepts/objects)** > > Understand the canonical record spine. > **[Semantic layer](/concepts/semantic-layer)** > > See how Atlas gives operational data shared meaning. # Semantic layer Source: https://docs.aioncx.com/concepts/semantic-layer Define business meaning once for analytics, decisions, and agents. The Atlas semantic layer converts operational records into governed context. It defines fields, dimensions, metrics, analyses, filters, relationships, and lineage independently from any single dashboard or agent prompt. ## Why semantics matter Without a shared semantic layer, two integrations can use the same word for different calculations—or different words for the same operational concept. Atlas makes those definitions inspectable and reusable. A semantic definition should answer: * What does this concept mean? * Which object or dataset owns it? * How is it calculated or resolved? * At what grain and time boundary is it valid? * Which filters and relationships are allowed? * Where did the result come from? ## One definition, many consumers Metrics and analyses should remain tied to objects, identities, relationships, time, and evidence. Governed semantics can then support charts, exports, forecasts, decision context, and agent answers without silently redefining meaning. Agentic execution should be explainable and auditable: the system should preserve the context used, the authority applied, the action taken, and the resulting outcome. > [!WARNING] > > A field label is not a semantic contract. Include units, grain, null behavior, time zone, allowed values, and lineage where they affect interpretation. See [Model your domain](/guides/model-your-domain) for a practical modeling sequence. # Build your first integration Source: https://docs.aioncx.com/guides/build-your-first-integration Take an Atlas integration from discovery to a safe production launch. Use this sequence before writing against an Atlas transport. It produces a small integration contract that can survive API and provider changes. **1. Define the use case** State the decision or workflow the integration enables. Name the operator, latency target, and failure consequence. **2. Identify source systems** Record each system of record or engagement, its ownership, and the direction of exchange. **3. Map objects and identities** List every exchanged object type, its stable source key, normalization rule, and system of record. Document ambiguous or missing identities. **4. Define scope with Lists** Identify which objects belong in the workflow and how membership changes. **5. Define cadence with Cycles** Describe when work repeats, which stages it follows, and who can advance it. **6. Connect API and event surfaces** Confirm the approved transport, authentication, freshness, volume, idempotency, backfill, and deletion behavior. **7. Validate outcomes** Test representative and adversarial records, compare source and Atlas results, monitor freshness and errors, and document rollback. **8. Review the audit trail** Confirm that identity changes, decisions, permissions, and execution outcomes are traceable to the responsible principal and evidence. ## Integration brief template ```text theme={"system"} Outcome: Systems of record: Atlas object types: Identity mappings: Semantic mappings: Direction and freshness: Expected volume: Authority required: Replay and reconciliation: Owner and escalation path: ``` > [!NOTE] > > Attach this brief when requesting Atlas v1 API or webhook access. It gives the Atlas team enough context to confirm the correct supported surface. # Model your domain Source: https://docs.aioncx.com/guides/model-your-domain Turn operational vocabulary into durable Atlas objects and semantics. A good Atlas model reflects how the organization reasons, without copying every source table or application screen. ## Start with nouns and decisions Collect the durable nouns in the workflow, then ask what decisions people make about them. A noun is a candidate object when it needs stable identity, history, relationships, governance, or workflow membership. ## Separate the layers | Question | Model as | | - | - | | What kind of thing is this? | Object type | | Which durable thing is it? | Object record | | What does a source call it? | Identity | | What is true about it? | Attribute | | How is it connected? | Relationship | | How is it measured? | Semantic metric | | Which workflow contains it? | List entry | | Where is it in that workflow? | Cycle stage | | What decision does the evidence support? | Analysis | | Who or what acted, and why? | Execution record | ## Review the model Before implementation, verify that: * display-name changes do not break identity; * provider replacement does not require a new business object; * relationships have clear direction and meaning; * metric definitions include grain and time boundaries; * workflow state is not duplicated as permanent object identity; * access and lifecycle requirements are explicit; * an agent can explain the meaning without relying on hidden prompt context. Use identities for external references, relationships for meaning, attributes for state, Lists for scope, Cycles for repeatability, analyses for decisions, and execution records for accountability. > [!TIP] > > Model the smallest complete slice that supports one real decision. Extend it when a new use case introduces genuinely new meaning. # AionCX documentation Source: https://docs.aioncx.com/index Use Atlas to run customer operations and Mach-1 to transcribe, analyze, and forecast through Build, REST, and MCP. AionCX connects the intelligence and daily work of your contact center. Use **Atlas** to plan staffing, review quality, understand customer needs, and maintain knowledge. Use **Mach-1** to turn recordings into usable results and forecast from numerical history. > **[Start using Atlas](/atlas/get-started)** > > Find your workspace, the tools for your role, and your first operational task. > **[Transcribe your first recording](/quickstart)** > > Send audio through Build, follow processing, and inspect the transcript. > **[Follow the Mach-1 pipeline](/mach1/overview)** > > Move from transcription and speaker attribution to findings, evaluations, evidence, and forecasting. > **[Connect an AI agent](/agents/quickstart)** > > Find the right documentation, credential, and tools for an authorized task. ## Choose the job | Your job | Start here | | - | - | | Forecast demand and prepare a schedule | [Resource Management](/atlas/resource-management) | | Review a conversation or quality evaluation | [Review interactions and evidence](/atlas/review-interactions) | | Edit, review, and publish knowledge | [Knowledge Operations](/atlas/knowledge-operations) | | Analyze an existing transcript | [Classification, extraction, and evaluation](/mach1/analysis) | | Predict future values from a numerical series | [Mach-1 forecasting](/mach1/forecasting) | | Build an integration | [API overview](/api-reference/overview) | ## What you need Atlas tasks require access to the selected workspace and the permissions for that work. Your navigation shows the pages available to your role. Mach-1 starts in [AionCX Build](https://build.aioncx.com). Build provides workspace setup, conversation submission, source connections, credentials, results, and usage. Applications and agents use the corresponding REST or MCP interfaces. Use the [glossary](/reference/metrics-and-terms) when you need a definition. The [Atlas concepts](/concepts/overview) explain the underlying model for developers extending the platform. # Model Context Protocol Source: https://docs.aioncx.com/integrations/mcp Connect agents to Mach-1 processing or native Atlas workforce tools. ## Mach-1 MCP: conversation processing and results Use the deployed `https://build.aioncx.com/api/mcp` endpoint with a personal `atlas_ingest_` scoped key from [Build Developers](https://build.aioncx.com/build/developers). A submit-and-read key can send an audio URL or transcript and read results. A read-only key can inspect authorized data. Organization ingest keys with more than one workspace grant must select a workspace. Native Zoom reads also require the issuing person's current recording authority. The key is checked against current grants on each call. The conversation tools include `mach1_get_transport`, `mach1_list_analysis_definitions`, `mach1_list_interactions`, `mach1_submit_audio_url`, `mach1_submit_transcript`, `mach1_get_status`, `mach1_get_transcript`, `mach1_get_results`, and `mach1_get_recording`. Discover the actual visible inventory with `tools/list`. Use `mach1_get_transport` to discover the direct receiver for audio bytes and large transcripts. MCP JSON requests have a 64 KiB limit. Submission is asynchronous and analysis is charged per configured transcript minute for each selected Definition; omitted Definition IDs request no analysis. Use stable idempotency keys for uncertain retries and follow `next_actions` for polling or pages. The runnable Mastra example and evaluation commands are in [`examples/mach1-mastra`](https://github.com/Xaqt/atlas/tree/main/examples/mach1-mastra). It calls these same tools with schema validation. An agent must receive real text/turns or an admitted interaction ID; a local filename alone gives it no file access. ## Mach-1 MCP: forecasting Forecasting uses the same application endpoint with explicitly granted `forecast:read` and `forecast:submit`. The tools are `mach1_list_forecast_sources`, `mach1_submit_forecast`, and `mach1_get_forecast`. Use the [forecasting request schema](/api-reference/forecasting/overview) for numerical history or a discovered metric. Submission takes `request` and a stable `idempotency_key`; reads take `run_id`, optional pagination, and the retained quantile selection. A native Atlas connection uses separately granted `atlas_list_forecast_sources`, `atlas_submit_forecast`, and `atlas_get_forecast` tools. See the [agent quickstart](/agents/quickstart) and [forecasting pricing](/mach1/forecasting-pricing). ## Documentation MCP: public search The public [Build on AionCX documentation](https://ventures-cx.mintlify.app) exposes a separate [Documentation MCP endpoint](https://ventures-cx.mintlify.app/mcp). It searches published Markdown content and does not submit or bill processing. Mintlify also generates [`llms.txt`](https://ventures-cx.mintlify.app/llms.txt) and [`llms-full.txt`](https://ventures-cx.mintlify.app/llms-full.txt). Keep the documentation-search endpoint and the Mach-1 processing endpoint distinct in agent configuration. ## Native Atlas MCP: workforce and scheduling After this release is deployed, open **Settings → External agents → Manage MCP connections** (`/atlas/settings/mcp`). You must have `manage_schedules` authority. Each tool also checks the same capability as its Atlas screen: directory/email discovery requires `manage_authorization`, employment and group-member reads require `view_workforce_context`, and group membership changes require `manage_workforce_roster`. A token never grants these capabilities by itself. Select the workspaces and whether to allow draft writes. Create a connection, then copy its token directly into your client's secret configuration. Never paste it into a conversation, source file, or a URL. The endpoint is `https://atlas.endeavorcx.com/api/mcp`. It uses stateless Streamable HTTP with JSON responses and protocol version `2025-06-18`. Authenticate with `Authorization: Bearer `. OAuth login is not offered by this release; use the explicit bearer-token connection. For Codex, make the token available to the client process as `ATLAS_MCP_TOKEN`, and configure: ```toml theme={"system"} [mcp_servers.atlas] url = "https://atlas.endeavorcx.com/api/mcp" bearer_token_env_var = "ATLAS_MCP_TOKEN" ``` Restart the MCP connection and verify `atlas_list_workspaces`. For this native-tool branch, do not use browser cookies, service-role keys, direct database connections, or Mach-1 ingest credentials. Custom connections expire in seven days; the explicit Superadmin profile stays valid until revoked while its issuer remains an active superadmin. Only a hash is stored. Revoke a connection from the same Settings page. Each domain intersects its workspace grants with the issuing person's current business authority. Removing that authority, disabling the person, revoking the token or expiry removes access. Custom connections keep fixed workspace selections. The explicit Superadmin profile follows active, organization-bound workspaces, including new ones, while retaining its separately selected action permissions. ## Roster and schedule workflow 1. `atlas_list_workspaces` discovers the authorized workspaces and durable IDs. 2. `atlas_list_people` pages through each workspace's directory. For an existing account absent from every workspace roster, an organization administrator can use `atlas_find_organization_person` with an exact email and one granted workspace. It can find org-only people, returns Atlas `person_id`, Auth-link status and association evidence, and marks the connection owner separately. A global person with no association to that organization is not exposed. Multiple matches remain ambiguous. Read `association_sources`, `status`, and `workspace_access`: agent assignment and employment do not themselves confer login access. Never guess or silently create duplicate people. 3. `atlas_get_scheduling_context` supplies scoped employment assignments. Respect effective dates and employment status. In enforcement mode, missing assignment context is a constraint, not permission to fall back to a person-only roster. 4. `atlas_list_schedule_groups` and `atlas_get_schedule_group` show existing groups, membership, operating hours and timezones. With write scope, use `atlas_create_schedule_group` and `atlas_add_schedule_group_member` as needed. 5. `atlas_list_schedules` checks existing periods and display names before `atlas_create_schedule` creates a **draft**. Supply an optional, clear `name` (for example, "Support team schedule — 2026-09-28"), local calendar dates for the period, and explicit UTC/offset timestamps for `atlas_add_schedule_shift`. `atlas_get_schedule` reads the saved display name back. Interpret the roster in its confirmed timezone and account for daylight-saving transitions. Existing schedules cannot overlap for the same group, even when named differently. 6. `atlas_list_activity_types` discovers break/meal activity slugs. `atlas_add_schedule_activity` places explicitly timed activities. A meal duration without a placement does not authorize inventing a break time. 7. `atlas_get_schedule` reads back the result and `atlas_validate_schedule` runs the existing work-rule validator. 8. With the separate **Schedule publication** permission, use `atlas_publish_schedule` after reviewing the draft and validation results. Pass the exact `updatedAt` returned by `atlas_get_schedule` as `base_updated_at`, a stable UUID `request_id`, and only acknowledge warnings that were reviewed. The existing Action command applies current authorization, work rules and approval policies. A `pending_approval` result is not published: retain the request and resume with the same arguments after human approval. Retry uncertain outcomes with the same request ID and viewed revision. Existing draft-write connections do not receive publication permission. Enable it explicitly in **Your connections**; a scheduling-write grant is also required. The database verifies the active token, owner, workspace and publication scope again at request and commit. Audit evidence records the real API-token actor and issuing person. Published schedules cannot be edited through this MCP surface. ## Workspace access roles Use `atlas_get_workspace_access` to read the existing person's role, status and `authorization_revision` in each granted workspace. With the separate **Workspace access roles** permission, call `atlas_set_workspace_access_role` with the observed revision, desired role and a stable UUID `operation_key`. Only use a null expected revision when the membership is absent. Confirm the person's identity before writing; these tools do not create users or invitations. Roles use the existing Atlas definitions: `member` grants full product access; `skyway_agent` and `desktop_agent` are restricted agent access. The connection owner must currently be an organization administrator for the workspace (or a root administrator). Self changes, restricting root users, stale revisions and foreign-organization targets are refused by the existing atomic access command. Pending invitations stay pending. The audit event records the owner and token. Read back each workspace after a change; retry lost responses with exactly the same operation key and arguments. Never assume granted workspaces are every workspace in the organization. Both new permissions can be enabled or revoked on an existing connection without rotating its token or changing its expiry or workspace grants. Scheduling and routing permissions remain separate. Writes use the existing scheduling services and their workspace, assignment, period, state, and work-rule checks. They are not automatically retried: after a lost response, read the target group or schedule to determine whether the write committed before submitting again. Group and schedule lists use existing service limits; a large roster that cannot be read completely must be reported as a constraint rather than treated as a complete employee inventory. The older semantic, inbox and mail MCP-shaped routes remain separate authenticated application surfaces. They are not included in these workforce connection grants. ## Onboard new Skyway people After the onboarding migration and application are deployed, enable **Create people with workspace access**, **Send login invitations**, and **Provision Skyway voice for people** under the existing connection's permissions. These are independent opt-ins: existing connections, including Superadmin profiles, retain their current grants. Updating them does not rotate the bearer token. Refresh the client's tool inventory afterward. Person creation needs `mcp:people:create` plus `mcp:access:write` in a granted workforce workspace. Invitations need `mcp:people:invite`. Both require current organization People & Access administration (or Organization Administrator / active superadmin). Voice provisioning needs `mcp:routing:voice:write` plus routing-read/write in a granted routing workspace and current `manage_ccaas_configuration`. Scheduling and AI-agent grants alone do not enable voice provisioning. 1. Find the authorized workspace and check `atlas_find_organization_person` using each confirmed human's exact email. For an existing person, use their confirmed `person_id` and the workspace-access tools. An ambiguous match needs an explicit identity choice. For a confirmed new human, call `atlas_create_person` with `workspace_id`, a stable UUID `operation_key`, `name`, `email`, and the explicit `access_role` (normally `skyway_agent`). Creation and restricted access commit together. The response includes the durable `person_id` and current access; it does not send email. 2. Read `skyway_get_person_voice_access`, then use `skyway_enable_person_voice` with the workspace and person IDs. Atlas uses the same person-first provisioning service as Voice Access. If multiple operational identities exist, the error returns candidates; supply only the confirmed `agent_object_record_id` as the recovery choice. The response includes `agent_object_record_id` for queue assignment and binding status. Credentials, passwords and provider secrets are never returned. 3. Inspect existing queues through `skyway_get_queue` and add the returned agent ID with `skyway_set_queue_agent`. Outbound-only people belong to their outbound queue; blended people also join the inbound service queue. Read each queue back. Membership affects future work immediately and does not make a phone registered or an agent ready. 4. Once the access role is final, explicitly call `atlas_invite_person` with a separate stable UUID `operation_key`, `person_id`, and `workspace_id`. The database reads and validates the selected person's saved email; the tool has no recipient override. Correct an incorrect email in the person record first. This sends email and grants no additional access. Inspect `atlas_list_person_invitations` for delivery, expiration, revocation and acceptance. A delivered invitation can still be pending; it is not proof of active login access. For several people, repeat this workflow with distinct creation and invitation keys per human. Reuse the exact key and arguments after an uncertain response. Person creation never merges identities by name/email. Voice retries recover the existing dedicated login; read status before retrying. A recorded successful invitation delivery is not resent. Failed or unrecorded deliveries can be retried and may send another email; delivery is not exactly once. Changing access after invitation preparation invalidates its revision, so use a fresh invitation key after reviewing the new access. A saved email change also rejects an old invitation key; use a fresh key after correcting the person record. Employment and scheduling remain separate. ## Connected agents missing from People Provider agent records are operational slots, not automatically scheduling people. An organization administrator can use `atlas_list_provider_agents` in a granted workspace to discover their source email, existing person link, state and `enrollment_key`. Discovery returns only the requested workspace's assignments. It fails explicitly if an underlying inventory may be truncated. To enroll a confirmed human, enable **Agent enrollment** on an existing connection under **Your connections**, or create a connection with **Allow enrolling connected agents as people for scheduling** enabled. Updating a connection preserves its token, expiry, workspace grants and scheduling permission. This adds the separate `mcp:people:enroll` scope; existing scheduling-write tokens do not gain it. Enrollment rechecks the owner's active organization-admin (or superadmin) authority on every call, as does discovery. Schedule-writing permission remains independent. Refresh client tool discovery after enabling enrollment. The existing bearer token continues to work; it does not need to be copied or replaced. Pass the source `provider_resource_id`, the unchanged `enrollment_key`, and either a confirmed new person's `name` or an existing, active workspace `person_id`. Do not infer that two people are the same from email or name alone. When multiple provider resources represent the same confirmed person, enroll the first, read back the person through `atlas_list_people`, and explicitly use that person ID for the other resource. Never create a new person for every matching source row. The existing atomic `atlas_enroll_provider_person` authority checks source assignment, conflicts and lifecycle generation and records an enrollment receipt with the human issuer. Retry a lost response with exactly the same arguments and key; do not replace the key on retry. Enrollment creates/links the scheduling identity only: no login membership, invitation, employment or schedule publication. Read `atlas_list_people` afterward before continuing with schedule groups. ## Verify time-off approval routing `atlas_get_timeoff_approval_setup` reads the published time-off practice, WFM Manager routing policy, and currently effective WFM Manager role holders in a granted workspace. It requires the issuing person's current `manage_time_off_context` capability. Use it to verify the existing routing before asking an agent to submit a request; it never installs a practice, adds a reviewer, or approves a request. A published schedule and time-off approval routing are separate setup checks. ## Grant boundaries ### QA Forms and LOB Lists After the Quality MCP application and command migration are deployed, enable **Quality access** on the existing connection in Settings → MCP Connections. Select the workspaces and grant reading, draft editing and release publication separately. Existing tokens retain their other access and do not gain Quality permissions automatically. Each call checks current evaluation-program authority; AI evaluator generation and release also require AI configuration authority. Use `atlas_list_quality_forms` and `atlas_get_quality_form` to read the existing Form, then `atlas_list_quality_scope_lists` and `atlas_get_quality_scope_list` to discover the existing shared LOB Lists of queues. Question scope uses a List ID; voice is the supported first release and has no channel selector. Outside the selected List, a question becomes N/A without changing the agent's score. `atlas_save_quality_form_draft` creates or edits a successor on the same Form. Preview supplied answers on canonical calls with `atlas_preview_quality_evaluation`, then inspect and generate the native evaluator with `atlas_preview_quality_prompt` and `atlas_create_quality_prompt_draft`. Review `atlas_preview_quality_release` before using `atlas_publish_quality_release`. The release commits the Form, evaluator and replacement steps in existing pipelines together, preserving target assignments and other steps. Stale plans are refused; use the same request UUID and exact input to recover a lost response. See the [Quality MCP workflow](https://github.com/Xaqt/atlas/blob/main/docs/atlas/mcp-quality.md) for the Nevada critical-failure and outside-LOB N/A setup. QA checks do not send surveys or implement a survey activation gate. ### Bind an inbound phone number Routing publication does not grant phone-number activation. Enable **Bind inbound numbers** under an existing connection's access settings, or explicitly select it when creating a custom connection. This adds `mcp:routing:numbers:write`, requires routing-write access and current call-configuration authority in every granted routing workspace, and preserves the token and its unrelated permissions. Existing connections and the superadmin creation preset do not gain it implicitly. Discover the number ID with `skyway_queue_options` or `skyway_get_queue`, then use `skyway_get_number_binding` to read its E.164, status, current route and `inbound_config_revision`, plus the last binding's reviewed version, actor and timestamp. Read and review the exact current published version through `skyway_get_route`. After the operator approves that cutover, call `skyway_bind_number` with `workspace_id`, `phoneNumberId`, `expectedRevision`, `flowId`, `expectedPublishedVersionId` and `approveRoutingChange: true`. Binding uses the existing activation service and atomic number/publication revision checks. It preserves outbound caller ID, recording override and number status. New inbound calls on an active number use the route immediately; existing calls keep their pinned version. An inactive number remains inactive. This does not publish a route, place a test call, grant audio-deletion authority or bypass recording/provider readiness checks. Read the binding back after success or a lost response. If the number revision or published route changed, inspect and review the new state rather than automatically retrying with a new revision. Live caller and agent testing is still required. ### Workspace access `atlas_list_workspaces` is the connection's scheduling-workspace grant list, intersected with its owner's current authority. It is not the list of every workspace in Atlas or even every workspace in the organization. Workspace role changes require explicit grants for each target workspace. An org admin can look up an org-only person from any granted workspace, but that lookup does not expand the connection's workspace grants or grant the person login access. If the desired workspace is absent, create a new connection selecting that workspace; existing connection workspace grants cannot be widened in place. Do this before attempting the write; never substitute a service-role query or browser action. # Integrations overview Source: https://docs.aioncx.com/integrations/overview Connect operational systems to the Atlas object and semantic model. Atlas integrates with systems of record, systems of engagement, communication platforms, data warehouses, and agent tools. Common categories include CRM, CCaaS, HRIS, WFM, payroll, CMS, knowledge bases, and analytics stores. An Atlas integration does more than move payloads. It preserves identity, maps source data into governed semantics, and defines what may happen when the system or an agent acts on that context. ## Integration patterns | Pattern | Best for | | - | - | | Batch ingestion | Historical loads and scheduled reconciliation | | Event-driven ingestion | Timely operational changes | | Query or export | Downstream analytics and governed delivery | | Webhooks | Atlas-originated notifications and workflow signals | | MCP | Tool discovery and agent-mediated actions | Availability varies by workspace and product surface. Confirm the supported transport before implementation. ## Production qualities A credible integration is idempotent, observable, replayable, and tenant-safe. It defines source ownership, identity normalization, deletion behavior, freshness, reconciliation, and escalation before go-live. > **[Build an integration](/guides/build-your-first-integration)** > > Follow the end-to-end readiness checklist. > **[Webhooks](/integrations/webhooks)** > > Prepare a safe event receiver. # Callbacks and processing status Source: https://docs.aioncx.com/integrations/webhooks Connect supported inbound deliveries and follow Mach-1 processing through the published status interfaces. Mach-1 accepts supported source deliveries and processes conversations asynchronously. Use the published status and result reads to determine when an admitted request is ready. ## Inbound deliveries [Build Sources](https://build.aioncx.com/build/sources) provides managed Zoom setup and a native Deepgram callback destination. Deepgram delivers a completed transcript to the one-time Basic Auth callback URL shown during setup. The optional `dg-token` check is configured for that connection. Destination and selected-analysis changes apply to future admissions. See [sources and transcript producers](/mach1/sources) for credential rotation, pause behavior, and existing transcript imports. ## Follow a conversation Retain the admitted interaction ID. Poll `GET /api/ingest/interactions/{interactionId}/status` with the scoped key, then retrieve its transcript and results. An agent can use `mach1_get_status` and the read tools. Follow returned `next_actions` and retain the input/transcript revision across pages. ## Follow a forecast Retain the submitted `run_id`. Read `GET /api/forecasts/{runId}` or call `mach1_get_forecast` until it completes or fails. See [forecasting](/mach1/forecasting). ## Outbound application events The published contracts use status reads for processing completion. A general customer-managed completion-webhook subscription and signing catalog is not part of those contracts. Use the status flow above for an integration built against this release. # Classify, extract, summarize, and evaluate Source: https://docs.aioncx.com/mach1/analysis Choose published Mach-1 analysis Definitions and turn audio or existing transcripts into structured findings with evidence. Mach-1 analysis applies selected published Definitions to a transcript. A Definition specifies the analysis and its output, such as a scenario classification, an extracted commitment, a summary, or an evaluation. ## Choose the result Open **Build → Analysis** or list published Definitions through REST or MCP. Inspect the description, version, service, and output metadata before selecting one. | Your question | Choose a Definition that produces | | - | - | | What happened in the conversation? | Scenario or classification results | | What did the customer need or the representative commit to? | Extracted findings and evidence | | What should someone read before taking over? | A structured summary | | How did the interaction meet the selected criteria? | An evaluation or scorecard result | Availability follows the published Definitions in your workspace. A fresh eligible self-service workspace receives **Interaction findings**. A configured summary or scorecard is a separate selection. ## Analyze your own transcript In **New request**, paste text or supply ordered turns. Select the analysis, processing tier, and scoped key. For applications, send `text` or `turns` through the direct transcript receiver and include `requested_definition_version_ids`. For MCP, use `mach1_list_analysis_definitions` and `mach1_submit_transcript`. An omitted or empty Definition list requests **no analysis**. Select at least one executable version when findings are your intended result. Plain text preserves one untimed passage. Ordered turns can preserve supplied speaker labels and second-based start/end times. The [source guide](/mach1/sources) explains how to use output from another transcript producer. ## Read the outcome Follow the request until its processing state is available, then inspect: 1. The input and transcript revision. 2. The selected Definition versions and their result states. 3. The returned findings or evaluations. 4. Each supporting evidence passage. A completed analysis can correctly return zero findings. An evaluation uses its published criteria; a reported commitment is evidence of the promise, with later completion established separately. ## Reuse results Applications can retrieve structured results through REST. Agents can use MCP results and follow pagination. Full Definition output schemas are available through the authorized schema URL returned by discovery. For forecasting, first aggregate the relevant findings into a defined numerical measure over a consistent interval. Then use [Mach-1 forecasting](/mach1/forecasting) with that history or an authorized registered metric. Read [usage and pricing](/mach1/usage) for the duration basis and separate analysis charges. # Errors, retries and limits Source: https://docs.aioncx.com/mach1/errors Handle admission failures and uncertain outcomes safely. The receiver returns structured errors for invalid credentials, unsupported input, size and duration limits, rejected URLs and unavailable service configuration. Direct audio is limited to 256 MiB and four hours; transcript JSON is limited to 25 MiB. The MCP JSON submission boundary is 64 KiB; use the receiver for audio and larger transcripts. Audio URL ingestion rejects private-network targets and unsafe redirects. An expired or re-signed URL can change the request intent. Replace the URL and use a new idempotency key; inspect the original result first if its outcome is unknown. A dropped connection after transfer may still have admitted the input. Repeat the *same* request with the same key before deciding it failed. A different key can admit duplicate work. An accepted input can wait for funding or fail during transcription or analysis. Keep reading its status and `next_actions`. Adding credit resumes eligible waiting stages through the existing recovery sweep. A checkout return URL is not proof of funding; wait for credit to appear in Usage after Stripe fulfillment. No general rerun endpoint is exposed. List and detail reads require current workspace authority. `interaction_id` and `external_conversation_id` filters are mutually exclusive. `source` accepts `api`, `deepgram` or `zoom`; a filtered cursor belongs to its original filters. Native Zoom additionally requires current recording visibility. Treat 403/404 as an authorization or visibility boundary rather than enumerating IDs. # Forecast from numerical history Source: https://docs.aioncx.com/mach1/forecasting Submit numerical series or authorized metrics to Mach-1, use supported drivers, and retrieve saved forecasts through REST or MCP. Mach-1 forecasting predicts future values from numerical history or an authorized registered metric. It is available independently of transcription: bring a series you already have, or use a measured series derived from your operational data. ## Before you start In **Build → Developers**, create a scoped key with **Submit forecasts** and **Read forecasts**. Conversation submission and read permissions are separate. You need a consistent interval, timezone, history start, numerical values, and forecast horizon. Choose `auto` for bounded method evaluation, or an explicitly supported method. Review [forecasting pricing](/mach1/forecasting-pricing). ## Submit a numerical series Save this synthetic example as `forecast.json`. It asks for four future daily points from one target series. ```json theme={"system"} { "method": "auto", "source": { "type": "numerical", "grain": "day", "timezone": "UTC", "historyStart": "2026-01-01T00:00:00Z", "horizon": 4, "series": [ { "id": "daily-contacts", "values": [42, 45, 48, 43, 51, 36, 31, 44, 47, 50, 46, 54, 38, 33, 46, 49, 52, 48, 56, 40, 35, 48, 51, 54, 50, 58, 42, 37] } ] } } ``` Set `MACH1_API_KEY`, `MACH1_WORKSPACE_ID`, and a new `MACH1_FORECAST_KEY` in your application's environment. Persist the key with this exact request before sending. ```bash theme={"system"} curl --fail-with-body -X POST \ "https://build.aioncx.com/api/forecasts?workspace_id=$MACH1_WORKSPACE_ID" \ -H "Authorization: Bearer $MACH1_API_KEY" \ -H "Idempotency-Key: $MACH1_FORECAST_KEY" \ -H 'Content-Type: application/json' \ --data-binary @forecast.json ``` A queued or running response returns `run_id`, `status`, and `results_url`. Keep the run ID and returned price. A 202 response means the work was accepted and is still in progress. ## Retrieve the forecast Set `MACH1_RUN_ID` to the returned run ID. ```bash theme={"system"} curl --fail-with-body --get \ "https://build.aioncx.com/api/forecasts/$MACH1_RUN_ID" \ -H "Authorization: Bearer $MACH1_API_KEY" \ --data-urlencode "workspace_id=$MACH1_WORKSPACE_ID" \ --data-urlencode "limit=50" \ --data-urlencode "quantiles=0.05,0.5,0.95" ``` Poll until the status is completed or failed. Completed responses contain forecast rows and an optional `next_cursor`. Retain the same run and quantile selection across pages. Rows include the interval, series/dimensions, `predicted_value`, available bounds, and method metadata. Available quantiles describe the forecast distribution. `predicted_value` can differ from P50: read `point_statistic`, `interval_statistic`, and `quantile_space` when interpreting them. ## Add drivers A numerical series can include up to eight numeric or categorical drivers. * A `past_only` driver supplies values for the history. * A `known_future` driver supplies values for history and the requested future horizon. * Its `mask` states which values are known. Optional `availableAt` timestamps preserve when information became available. * Use `auto` or `timestral` for explicit numerical drivers. Align driver arrays with the target history and horizon. A backtest must use only the information available at each forecast origin. Supported drivers and uncertainty output are included in the bounded request. ## Forecast a registered metric Use MCP `mach1_list_forecast_sources` with the granted `workspace_id` to discover available metrics, dimensions, and grains. Then submit a `source.type` of `metric` with the discovered reference and an explicit history window. Discovery establishes catalog support. The run separately checks source access and the requested observed history. ## Use MCP Discover visible tools, then call `mach1_submit_forecast` with `request` set to the same JSON object and a stable `idempotency_key`. Read the result with `mach1_get_forecast`. See [the agent quickstart](/agents/quickstart) and [forecasting REST reference](/api-reference/forecasting/overview). ## Limits and recovery | Limit | Current boundary | | - | - | | Target series | 4 per numerical request | | Historical target buckets | 32,768 total across numerical series | | Future forecast points | 10,000 total across numerical series | | Drivers | 8 per series | | Auto evaluation | Up to 3 folds | | REST request body | 1 MiB | | Complete MCP request | 64 KiB | | Grains | 15 minutes, 30 minutes, hour, day, week | Use `null` for missing observations and zero for measured zero. Numerical series in one request must have the same history length and unique IDs. After an uncertain submission, retry the identical request with its original key. A changed request needs a new key. Read retained results without starting another run. For 403, check forecast grants, workspace selection, and current source access. For 503, retain the request and follow the retry guidance. # Forecasting pricing Source: https://docs.aioncx.com/mach1/forecasting-pricing Understand the current zero-dollar Mach-1 forecast charge and where to check account-specific processing rates and credit. Mach-1 forecasting currently records **USD 0 per bounded forecast request**. This applies to numerical-series and registered-metric requests through the existing forecasting interfaces. | Work | Current charge | | - | - | | Submit a bounded forecast | USD 0 | | Bounded Auto evaluation and supported drivers | Included | | Available uncertainty outputs | Included | | Retrieve a saved forecast | USD 0 | The [forecasting guide](/mach1/forecasting) describes the supported input, method, interval, series, and transport limits. REST and MCP use the same forecast execution and retained results. ## Check the request price Submission returns the price retained for that run. Keep the run ID and its recorded price when checking a request. An uncertain retry with the same key and payload recovers the existing request; retrieving a saved result does not create another forecast. ## Other Mach-1 services and credit Transcription and selected conversation analyses use their configured rates and the existing Mach-1 balance. Open [Usage and billing](https://build.aioncx.com/build/usage) for the actual rates, starter credit, offered top-up amounts, and authorized billing details for your account. Starter credit and top-up denominations follow the account's deployment configuration. See [Usage and pricing](/mach1/usage) for their charging basis and funding behavior. # Mastra agent example Source: https://docs.aioncx.com/mach1/mastra Connect a runnable Mach-1 client and discover tools available to its scoped credential. Create a client with the following files. Set `MACH1_MCP_URL=https://build.aioncx.com/api/mcp` and `MACH1_API_KEY` to a personal scoped ingest key from [Build Developers](https://build.aioncx.com/build/developers). Keep a separate key for each customer. For a key that grants multiple workspaces, append `?workspace_id=` to the MCP URL. ## Install Use Node.js 22.17 or later. In a new directory: ```bash theme={"system"} npm init -y npm pkg set type=module npm install --save-exact @mastra/core@1.75.0 @mastra/mcp@2.2.0 @modelcontextprotocol/client@2.0.0 tsx@4.20.6 ``` ## Connect Save this as `client.ts`. It uses the supported protocol, bounded timeouts, and output-schema validation. The key stays in the HTTP authorization header. ```typescript client.ts theme={"system"} import { MCPClient } from "@mastra/mcp"; import { AjvJsonSchemaValidator } from "@modelcontextprotocol/client/validators/ajv"; const url = process.env.MACH1_MCP_URL; const key = process.env.MACH1_API_KEY; if (!url || !key) throw new Error("Set MACH1_MCP_URL and MACH1_API_KEY."); export const schemaValidator = new AjvJsonSchemaValidator(); export const mcp = new MCPClient({ servers: { mach1: { url: new URL(url), protocolVersion: "legacy", connectTimeout: 30_000, requestInit: { headers: { Authorization: `Bearer ${key}` } }, timeout: 660_000, jsonSchemaValidator: schemaValidator, }, }, }); ``` Save this as `smoke.ts` to check the connection without generating an agent response or submitting a conversation: ```typescript smoke.ts theme={"system"} import { mcp } from "./client.js"; try { const tools = await mcp.listTools(); const names = Object.keys(tools); if (!names.some(name => name.includes("mach1_get_transport"))) throw new Error("Mach-1 transport tool unavailable"); process.stdout.write(`${JSON.stringify({ connected: true, tools: names }, null, 2)}\n`); } finally { await mcp.disconnect(); } ``` Set `MACH1_MCP_URL` and `MACH1_API_KEY` in your local environment, then run: ```bash theme={"system"} npx tsx smoke.ts ``` ## Ask an agent about a conversation Save this as `agent.ts`. Set `MASTRA_MODEL` to your enabled provider/model and configure that provider's API credential in your local environment. Set `MACH1_INTERACTION_ID` to an admitted conversation. ```typescript agent.ts theme={"system"} import { Agent } from "@mastra/core/agent"; import { mcp } from "./client.js"; const task = process.argv.slice(2).join(" ") || "Identify commitments in this conversation and cite the evidence."; const interactionId = process.env.MACH1_INTERACTION_ID; const idempotencyKey = process.env.MACH1_IDEMPOTENCY_KEY; try { const tools = await mcp.listTools(); const agent = new Agent({ id: "mach1-conversation-analyst", name: "Mach-1 conversation analyst", instructions: `Use the Mach-1 tools to discover authorized definitions, select or submit the input, poll processing, and cite only findings with evidence. ${interactionId ? `A known interaction ID is ${interactionId}.` : "Discover a relevant authorized interaction or ask for an input."} ${idempotencyKey ? `For a new submission, reuse this caller-generated idempotency key: ${idempotencyKey}.` : "Do not submit until the application supplies MACH1_IDEMPOTENCY_KEY."} Never invent findings or substitute transcript text for evidence.`, model: process.env.MASTRA_MODEL || "openai/gpt-5.6-luna", tools, }); const result = await agent.generate(task); process.stdout.write(`${result.text}\n`); } finally { await mcp.disconnect(); } ``` ```bash theme={"system"} npx tsx agent.ts 'Find commitments and cite evidence' ``` For a new submission, your application must create and persist `MACH1_IDEMPOTENCY_KEY` before invoking the agent. Reuse the same key and payload after an uncertain result. Keep credentials outside source control. Contributors with repository access can also run the [full schema-check and evaluation harness](https://github.com/Xaqt/atlas/tree/main/examples/mach1-mastra). Pass text/turns or an already admitted interaction ID. A local filename alone does not give a remote agent file access; upload or read the file in the application first. MCP submission and results use the same authorized owners as REST. The conversation `mach1_*` tools include submission, Definition discovery, interaction listing, status, transcript, results and recording. Use the [Mach-1 MCP guide](/integrations/mcp) for credential boundaries. Definition discovery returns compact metadata, including the version ID, service, starter marker and output-schema digest. The full schema is available at each `output_schema_url`; resolve that relative URL against your Mach-1 origin and send the same Bearer key. The REST URL selects the exact published version and rechecks workspace access. This keeps large schemas out of the 64 KiB MCP response while preserving the full schema for applications that need it. This endpoint performs processing and can incur configured charges. Mintlify's separate **Documentation MCP** searches these public docs at the published docs site's `/mcp`; it does not submit inputs or charge the Mach-1 ledger. ## Forecasting with the same client A key with forecast permissions also exposes `mach1_list_forecast_sources`, `mach1_submit_forecast`, and `mach1_get_forecast`. The tool inventory follows the key's current grants. Use [forecasting](/mach1/forecasting) for the request and the [agent quickstart](/agents/quickstart) for discovery, submission, polling, and pagination. # The Mach-1 pipeline Source: https://docs.aioncx.com/mach1/overview Move from audio to transcripts, classifications, extracted findings, evaluations, evidence, and forecasts. Mach-1 turns recordings and existing transcripts into structured results, and forecasts future values from numerical history. Start with the input you already have and choose the processing you need. ## 1. Transcribe Send a recording for transcription. Inspect the returned text, available timing, and speaker labels. Use [the quickstart](/quickstart) for your first recording and [transcription](/mach1/transcription) for input and output details. ## 2. Attribute speakers Where speaker attribution is available, turns identify different speakers. A speaker label describes the source attribution; use additional identity evidence to associate it with a person. Supplied text preserves the labels and timing you provide. ## 3. Classify and extract Select published analysis Definitions to identify scenarios, reasons for contact, entities, actions, and commitments. The Definition determines the output and service being requested. See [classification, extraction, and evaluation](/mach1/analysis). ## 4. Summarize and evaluate Request a published Definition that produces the summary or evaluation you need. An evaluation applies its own configured criteria and version. Requesting transcription alone does not select analysis. ## 5. Use structured results and evidence Retrieve the transcript, findings, evaluations, and their source references. Check the input revision and processing state, then follow evidence back to the relevant passage. Read [results and evidence](/mach1/results). ## 6. Forecast Supply numerical history or select an authorized registered metric, choose the interval and horizon, and retrieve the saved forecast. Supported drivers can add information available at forecast time. Extracted findings can contribute to a measured time series. Define its metric, interval, filters, and history before using that series for a forecast. The [forecasting guide](/mach1/forecasting) starts directly from numerical input. ## Choose an entry point | Your input | Start with | | - | - | | Recording | [Transcription](/mach1/transcription) | | Existing transcript | [Analysis](/mach1/analysis) | | Existing admitted conversation | [Results and evidence](/mach1/results) | | Numerical history or a registered metric | [Forecasting](/mach1/forecasting) | Use Build for the available browser workflows and credential management, REST for applications, and MCP for authorized agents. Check [usage and pricing](/mach1/usage) before submitting paid work. # Results and evidence Source: https://docs.aioncx.com/mach1/results Inspect asynchronous status, transcript, findings and source audio. `POST /v1/ingest/audio`, `/audio-url` and `/transcripts` return an admitted interaction ID after acceptance. Processing continues asynchronously. Poll `GET /api/ingest/interactions/{interactionId}/status`, then read `/transcript`, `/results` and `/recording` with a scoped key. [Build Requests](https://build.aioncx.com/build/requests) uses the corresponding human session routes. The interaction ID identifies the conversation. An external conversation ID is source supplied and may recur across actors or connections. Exact identifier search returns every authorized match with its source; it cannot prove whether a particular timed-out delivery was admitted. Use a stable `Idempotency-Key` for uncertain retries, and inspect the returned interaction and input revision. A changed input under the same external ID adds an input revision. The same idempotency key must be reused only with the original request. Results are tied to a concrete input revision and transcript producer/revision. Cursor pages pin these choices. Follow `next_cursor` and retain the requested revision when navigating evidence. A changed revision starts fresh pagination. Large responses expose lossless `parts` with JSON paths; string parts include original character offsets and turn indices. Do not infer timestamps from character positions or speaker labels from plain text. MCP result reads include findings, evidence and Definition version metadata. They omit the repeated Definition specification and compiled schema. For that full snapshot, use the authenticated REST `/api/ingest/interactions/{interactionId}/results` read with the same revision and scoped key. The result state distinguishes waiting, failed, partial, quarantined and completed. Completed can contain zero findings. Finding evidence references transcript passages. Timed passages can seek available original audio; untimed passages point to text ranges. A recording may be absent. Read permission does not imply billing-ledger permission: billing details appear only in the organization's authorized Usage view. The API returns `next_actions` when a poll or next page is useful. These are guidance only; reading a suggestion never starts paid work. # Sources and transcript producers Source: https://docs.aioncx.com/mach1/sources Choose a connected source or submit existing producer output. [Build Sources](https://build.aioncx.com/build/sources) connects native Zoom and Deepgram deliveries to a workspace. Zoom uses its registered authorization, provider resources and destination assignments. Deepgram requires a destination workspace and optional `dg-token` identifier; Build displays its Basic Auth callback URL once. Configure Deepgram to deliver a completed transcript to that URL. No Deepgram API key or account lookup is used. Select published Definition version IDs before saving a destination. Changing the destination or analysis choice applies to future admissions; an already accepted input retains its original assignment and revisions. Pause stops new callbacks with a non-2xx response while admitted work continues. Rotation keeps the connection identity and replaces the callback credential. Provider retry behavior determines whether a failed delivery arrives again. Amazon Connect, NICE, Five9, 8x8, Cisco Webex Contact Center and RingCentral have catalog entries; Connect becomes usable when their adapter is installed. This page does not imply those adapters are active. To use **existing** Google Speech-to-Text, ElevenLabs or another producer, send their output through the [direct transcript API](/quickstart). Map supplied text, speaker and second-based start/end fields to ordered `turns`; retain the provider's original identifier as `external_conversation_id`. The admission source is `api`, because this is an API submission. It does not create a provider connection or make the provider transcribe again. An untimed text passage remains untimed. Deepgram's native callback has its own `deepgram` source provenance. The direct receiver accepts WAV, MP3 or M4A multipart audio, audio URLs, plain text and ordered turns. It produces the same interaction and transcript-availability dispatch used by connected sources. Find its URL in Build → Developers. # Transcribe audio Source: https://docs.aioncx.com/mach1/transcription Submit an audio file or URL to Mach-1 and inspect the resulting transcript, speaker attribution, and source evidence. Mach-1 transcription converts a recording into text for review and further analysis. You can upload an audio file, provide an HTTPS audio URL, or connect a supported delivery source. ## Before you start Open [AionCX Build](https://build.aioncx.com) and select the correct workspace. You need a key with submission and read access to send the recording and inspect the result. The [quickstart](/quickstart) covers the browser steps. Direct uploads accept WAV, MP3, and M4A. The current direct-audio boundary is 256 MiB and four hours. An audio URL must be reachable by the processing service and pass its destination checks. Discover the workspace receiver URL in Build → Developers or through MCP transport discovery. ## Send a recording In **New request**, select an audio file or audio URL. Choose **No analysis** when you want transcription alone, or select the published analysis versions to run afterward. Choose Standard or Reserved processing and connect your scoped key. Reserved processing starts in its overnight or weekend window. Send the request once and retain the admitted interaction ID. For an application, use the direct receiver's `/v1/ingest/audio` or `/v1/ingest/audio-url` contract in the [REST reference](/api-reference/overview). MCP can submit an audio URL; local audio bytes use the discovered direct upload endpoint. ## Inspect the transcript Open the request and check its status before reading the transcript. * Review the text and available speaker turns. * Use source timing when supplied to locate the relevant part of the recording. * Check which input and transcript revision you are reading. * Confirm important names, amounts, dates, and commitments against the source. Speaker attribution and timing can be absent. Plain supplied text remains an untimed passage. Treat missing information as missing rather than reconstructing it from character positions. ## Add analysis Choose the [analysis](/mach1/analysis) you need before submitting when transcription and analysis should run together. Analysis has its own charge per selected Definition. Existing transcript submissions skip transcription charges. ## Recover a request For a timeout or lost response, reuse the original request and idempotency key. Processing may already have accepted the recording. A request waiting for funding retains its identity. Add credit through Usage and follow the existing status. See [errors and retries](/mach1/errors) for URL, size, permission, and funding failures. # Usage and pricing Source: https://docs.aioncx.com/mach1/usage Understand shared Mach-1 credit, audio-duration charges, current forecast charges, and funding. [Build Usage and billing](https://build.aioncx.com/build/usage) shows the organization's available credit, holds, stage history, workspace/service usage and configured top-up denominations to authorized billing viewers. Organization administrators can open a native zero-credit account for an existing organization and start checkout. A new eligible self-service organization receives only its configured one-time starter entry; the amount is a deployment setting, not a fixed published price. Conversation-service retail pricing is configured per deployment and shown in Build as **USD per audio hour**. A submission selects Standard or Reserved. Reserved starts processing on weekends or between **7 p.m. and 7 a.m. Eastern time**, following daylight saving time. Choose the tier for each submission; adding credit does not change the tier. The API uses `pricing_tier: "standard" | "reserved"` (default Standard), and an uncertain retry must keep the same tier and idempotency key. Each stage is charged for its duration at its selected tier. Audio transcription has its own rate. Classification and scenarios, extraction, and scorecards and evaluations each have separate analysis rates, applied per requested Definition. Supplying a transcript has no transcription charge. Timed transcripts use their full timed extent; untimed transcripts use an estimated duration from the configured words-per-minute rate. The estimate is a billing basis, not an observed recording duration. Charges retain the pinned rate version and fractional-minute precision. Admission and reads remain available when credit is exhausted. Paid stages wait for funding and resume through the existing sweep after Stripe's authoritative webhook credits the account. Returning from checkout may show pending confirmation until funding posts. Top-up buys the selected credit amount; applicable tax is shown separately and does not add spendable credit. Paid invoices are available when invoice generation is enabled. Refunds remove the corresponding purchased credit, with tax excluded from the credit adjustment. Top-up does not change the workspace, source assignments, keys or input revisions. There are no subscriptions, auto-recharge or separate production credentials. ## Forecasting Forecasting currently records **USD 0 per bounded forecast request**. Retrieving saved forecast results also has no processing charge. Read [forecasting pricing](/mach1/forecasting-pricing) for the current forecast behavior and retained request price. Transcription and selected conversation analyses continue to use their configured duration rates and shared balance. Starter-credit amounts and offered top-up denominations remain deployment settings. Use the values shown in Build Usage and billing for your account. # Transcribe your first recording Source: https://docs.aioncx.com/quickstart Use AionCX Build to submit audio, follow processing, inspect the transcript, and add analysis. Get your first Mach-1 result by submitting a short recording through [AionCX Build](https://build.aioncx.com). Retain its interaction ID, follow processing, and inspect the transcript. ## 1. Open your workspace Sign up with email and password, confirm your email, and enter Build. Existing invited people keep their assigned workspace selection. Check the workspace name before submitting. A fresh eligible self-service workspace receives the published **Interaction findings** Definition. Your workspace, keys, sources, and history continue when you add credit. ## 2. Submit audio Open [New request](https://build.aioncx.com/build/requests/new). Upload a WAV, MP3, or M4A recording, or provide an HTTPS audio URL. Choose **No analysis** for transcription alone. To inspect findings from the same request, select **Interaction findings** or another available published analysis. Review the configured rate and choose Standard or Reserved processing. In **Connect your key**, create a personal scoped key or connect an existing key with submission and read access. Send the request and retain its interaction ID. Reserved processing starts overnight, from 7 p.m. to 7 a.m. Eastern time including daylight saving time, or on weekends. ## 3. Inspect the result Open [Requests](https://build.aioncx.com/build/requests), select the request, and follow its status. Inspect the transcript, available speaker attribution, and source timing. If analysis was selected, open its findings and supporting evidence. Accepted work can wait for funding. Add credit through [Usage](https://build.aioncx.com/build/usage), then continue following the same request. A completed analysis can return zero findings. ## 4. Continue through the pipeline Read [analysis](/mach1/analysis), [results and evidence](/mach1/results), and [forecasting](/mach1/forecasting) for the next job. Existing transcripts and numerical history have their own direct entry points. You can also connect [supported sources](/mach1/sources) for future deliveries. ## Start from an existing transcript through REST Build displays the receiver URL for your workspace. Copy it into `MACH1_TRANSCRIPT_URL`, then discover a published Definition ID in **Build → Analysis** or `GET /api/ingest/analysis-definitions`. ```bash theme={"system"} export ATLAS_INGEST_TOKEN='' export MACH1_TRANSCRIPT_URL='' export MACH1_WORKSPACE_ID='' export MACH1_DEFINITION_VERSION_ID='' export MACH1_IDEMPOTENCY_KEY='' curl -sS -X POST "$MACH1_TRANSCRIPT_URL" \ -H "Authorization: Bearer $ATLAS_INGEST_TOKEN" \ -H "Idempotency-Key: $MACH1_IDEMPOTENCY_KEY" \ -H 'Content-Type: application/json' \ --data "{\"workspace_id\":\"$MACH1_WORKSPACE_ID\",\"external_conversation_id\":\"demo-1\",\"pricing_tier\":\"standard\",\"text\":\"We agreed to send the revised proposal on Friday.\",\"requested_definition_version_ids\":[\"$MACH1_DEFINITION_VERSION_ID\"]}" ``` The receiver returns an `interactionId`. Poll `GET https://build.aioncx.com/api/ingest/interactions/{interactionId}/status` with the same bearer token and `X-Workspace-Id` header; then request `/results` and `/transcript`. Keep the original idempotency key for an uncertain retry. Reusing an external conversation ID with changed content creates a new input revision under the same interaction. To skip paid analysis, submit `"requested_definition_version_ids":[]`. Omission also requests no analysis in API and MCP calls. Supplied transcripts do not incur transcription charges; each selected Definition uses its service's configured rate per transcript duration. See [Usage and pricing](/mach1/usage). For an agent connection, use the [agent quickstart](/agents/quickstart). # Metrics and terms Source: https://docs.aioncx.com/reference/metrics-and-terms Understand Atlas forecast groups, scheduling groups, demand, coverage, shrinkage, findings, and evidence. Use these definitions when reading Atlas results and configuring workforce work. Check the selected metric's own calculation, scope, exclusions, and time basis before comparing values. | Term | Meaning | | - | - | | Workspace | The operational scope whose data, configuration, and permissions apply to your work | | Agency | A named area of operational work in Atlas, such as Resource Management or Knowledge Operations | | Interaction | A durable conversation identity, which can have multiple input and analysis revisions | | Definition | A published, versioned specification for a selected analysis and its output | | Finding | A structured observation produced from source material | | Evidence | The source passage or record supporting a finding or result | | Forecast group | The defined work scope, forecast configuration, and service targets used to plan demand | | Scheduling group | The people and planning configuration used to prepare schedules | | Forecast horizon | The number of future intervals to predict | | Forecast point | One predicted future interval for one target series; additional quantiles describe that point | | Grain | The interval of a series, such as 15 minutes, an hour, or a day | | Staffing requirement | The number of people required over an interval under the selected demand and service assumptions | | Net demand | The underlying staffing demand before grossing up for the configured loss assumptions | | Gross requirement | The staffing requirement after the applicable loss assumptions and rounding | | Productive coverage | Productive scheduled supply compared with exact net demand, accounting for the explicitly assessed residual loss | | Residual unplanned shrinkage | The additional loss remaining after scheduled nonproductive activity has already been accounted for | | Adherence | Comparison of actual activity with the published schedule and its activity mapping | | Occupancy | A workload-to-capacity ratio whose included work, available time, and interval must be stated by the selected metric | | Quantile | A value at a selected level of the forecast distribution, where the method supplies it | ## Time and scope A forecast, actual, or staffing requirement belongs to a particular metric, work scope, interval, and timezone. Compare like scopes. Daily and weekly boundaries follow the configured timezone, including daylight saving time. A full-interval forecast and actual work observed so far are different quantities. Current intraday observations may still be provisional. ## Missing values An observed zero is a measured value. Missing history, unreadable evidence, and work still processing are separate states. Resolve the stated limitation before using a missing value as a planning input. ## Avoid counting loss twice Scheduled meals, breaks, and other nonproductive activities already reduce productive supply. Residual unplanned shrinkage represents the remaining additional loss. For example, a residual of `0.10` means a ten-percent additional loss assumption; it does not describe total shrinkage unless that is how the full calculation has been defined. ## Interpret a forecast `predicted_value` is the operational point returned by the method. It may differ from P50. Inspect `point_statistic`, the returned quantiles, interval fields, and method metadata before interpreting it as a mean or median. See [forecasting](/mach1/forecasting) for numerical examples and [Resource Management](/atlas/resource-management) for the staffing workflow.