Skip to main content

Managers

Manage multi-agent managers programmatically: create and configure them, wire up sub-agents, publish and roll back versions, inspect conversation history and statistics, and control sharing and ownership.

All paths on this page are relative to https://api.autessa.com/autessa_poweruser/managers. Every request is a POST with a JSON body, and every ID is an opaque string. See the Poweruser API overview for authentication and conventions.

The manager object​

A manager coordinates a team of agents: it reasons about the user's request, delegates tasks to its sub-agents, and composes their results into a response. Managers are returned as an object keyed on managerType; the only type today is SIMPLE.

  • Name
    managerId
    Type
    string
    Description

    Unique manager identifier.

  • Name
    managerType
    Type
    string
    Description

    Currently always SIMPLE. Immutable after creation.

  • Name
    versionNumber
    Type
    integer
    Description

    Version number when reading a specific published or archived version; absent on the draft working copy.

  • Name
    name
    Type
    string
    Description

    Display name.

  • Name
    description
    Type
    string
    Description

    What the manager does.

  • Name
    instructions
    Type
    string
    Description

    The system prompt. Defaults to "Coordinate and manage the agents to accomplish the task". May contain @@{variableName}@@ placeholders filled from promptTemplateVariables at execution time.

  • Name
    model
    Type
    string
    Description

    Model alias: BIG_INSTRUCTION_FOLLOWING_REASONING, BIG_INSTRUCTION_FOLLOWING, SMALL_INSTRUCTION_FOLLOWING, VIBE_CODING, or AUTESSA_120B. Defaults to SMALL_INSTRUCTION_FOLLOWING.

  • Name
    voiceConfig
    Type
    object
    Description

    Voice settings for audio output: voiceModel (SMALL, MEDIUM, LARGE) and voiceName.

  • Name
    promptTemplateVariables
    Type
    object
    Description

    Map of variable name to argument definition (description, isRequired, argumentSchema — a JSON Schema object).

  • Name
    evaluationNotes
    Type
    string
    Description

    Grading rubric used by automated evaluation.

  • Name
    lastPublishedTime
    Type
    string
    Description

    ISO-8601 timestamp of the last publish, or absent if never published.

  • Name
    tags
    Type
    array<string>
    Description

    Free-form organizational tags.

  • Name
    maxIterations
    Type
    integer
    Description

    SIMPLE — maximum coordination-loop iterations per turn (default 10). Each sub-agent delegation consumes an iteration.

  • Name
    agents
    Type
    array<Agent>
    Description

    SIMPLE — the sub-agents the manager can delegate to. Reads return agent summaries; when updating, each entry only needs its agentId — the manager stores references and resolves the agents' published versions at execution time. See Agents.

Manager object (SIMPLE)
{
  "managerId": "mZ8kW3qN5d",
  "managerType": "SIMPLE",
  "name": "Customer Success Manager",
  "description": "Coordinates triage, research, and reply agents for support requests.",
  "instructions": "Coordinate and manage the agents to accomplish the task",
  "model": "BIG_INSTRUCTION_FOLLOWING",
  "voiceConfig": {
    "voiceModel": "SMALL",
    "voiceName": "FEMALE"
  },
  "promptTemplateVariables": {},
  "evaluationNotes": "A good conversation resolves the request end to end.",
  "lastPublishedTime": "2026-06-28T17:42:10",
  "tags": ["support"],
  "maxIterations": 10,
  "agents": [
    {
      "agentId": "V1StGXR8Z5",
      "agentType": "SIMPLE",
      "name": "Support Triage Agent",
      "description": "Classifies inbound support tickets and drafts replies."
    }
  ]
}

Versioning and access levels​

Managers follow the platform-wide draft/published model (see the Versions guide):

  • Draft — /update always edits the draft working copy.
  • Published — /publish snapshots the draft as a new published version; the previously published version becomes archived.
  • Rollback — /rollback republishes an archived version. The draft is untouched.

Endpoints enforce the caller's access level on the manager (the poweruser key acts as its linked user):

OperationRequired access
get, get-all, versions, conversations, conversation, statistics, get-sharing-detailsAny access (READ or higher)
updateWRITE, PUBLISH, or ADMIN
publish, rollbackPUBLISH or ADMIN
delete, shareADMIN
transfer-ownershipOwner only

Create a manager​

POST/managers/create

Creates a new manager as a draft. managerName and managerDescription are both required — creation fails with an error message if either is blank. Wire up instructions, model, and sub-agents afterwards with /update, then /publish to make it executable.

Request parameters​

  • Name
    managerType
    Type
    string
    Description

    Currently only SIMPLE.

  • Name
    managerName
    Type
    string
    Description

    Display name. Must be non-blank.

  • Name
    managerDescription
    Type
    string
    Description

    Description of the manager's purpose. Must be non-blank.

Response​

  • Name
    manager
    Type
    Manager
    Description

    The newly created manager object.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

curl https://api.autessa.com/autessa_poweruser/managers/create \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "managerType": "SIMPLE",
    "managerName": "Customer Success Manager",
    "managerDescription": "Coordinates triage, research, and reply agents for support requests."
  }'
Response (truncated)
{
  "manager": {
    "managerId": "mZ8kW3qN5d",
    "managerType": "SIMPLE",
    "name": "Customer Success Manager",
    "description": "Coordinates triage, research, and reply agents for support requests.",
    "instructions": "Coordinate and manage the agents to accomplish the task",
    "model": "SMALL_INSTRUCTION_FOLLOWING",
    "maxIterations": 10,
    "agents": []
  },
  "errors": []
}

Get a manager​

POST/managers/get

Retrieves a manager's full configuration, including its sub-agent list.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to fetch.

Response​

  • Name
    manager
    Type
    Manager
    Description

    The manager object.

  • Name
    permission
    Type
    string
    Description

    The calling user's access level on this manager: READ, WRITE, PUBLISH, or ADMIN.

  • Name
    voiceOptionsList
    Type
    array<VoiceOptions>
    Description

    Voice models available to the company, each with voiceModel and a voices object listing builtInVoiceNames and customVoiceNames (custom voice clones, on supported models).

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

curl https://api.autessa.com/autessa_poweruser/managers/get \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "managerId": "mZ8kW3qN5d" }'
Response (truncated)
{
  "manager": {
    "managerId": "mZ8kW3qN5d",
    "managerType": "SIMPLE",
    "name": "Customer Success Manager",
    "model": "BIG_INSTRUCTION_FOLLOWING",
    "maxIterations": 10,
    "agents": [
      { "agentId": "V1StGXR8Z5", "name": "Support Triage Agent" }
    ]
  },
  "permission": "ADMIN",
  "voiceOptionsList": [
    {
      "voiceModel": "SMALL",
      "voices": {
        "builtInVoiceNames": ["FEMALE", "MALE"],
        "customVoiceNames": []
      }
    }
  ],
  "errors": []
}

List all managers​

POST/managers/get-all

Lists every manager visible to the linked user, grouped by how they have access. Entries are lightweight summaries — use /get for full configuration.

Request parameters​

None — send an empty object {}.

Response​

  • Name
    ownedManagers
    Type
    array<Manager>
    Description

    Managers the linked user owns.

  • Name
    companySharedManagers
    Type
    array<Manager>
    Description

    Managers shared with the whole company.

  • Name
    sharedWithMeManagers
    Type
    array<Manager>
    Description

    Managers shared specifically with the linked user.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/get-all \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "ownedManagers": [
    {
      "managerId": "mZ8kW3qN5d",
      "managerType": "SIMPLE",
      "name": "Customer Success Manager",
      "description": "Coordinates triage, research, and reply agents for support requests.",
      "tags": ["support"],
      "lastPublishedTime": "2026-06-28T17:42:10"
    }
  ],
  "companySharedManagers": [],
  "sharedWithMeManagers": [],
  "errors": []
}

Update a manager​

POST/managers/update

Replaces the manager's draft configuration with updatedManager. This is a whole-object update: fetch the draft with /get, modify it, and send the full object back. To change the sub-agent team, set agents to the desired list — each entry only needs its agentId. Published versions are unaffected until you /publish.

Requires WRITE, PUBLISH, or ADMIN access.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to update.

  • Name
    updatedManager
    Type
    Manager
    Description

    The complete manager object to store as the new draft, using the manager object shape; managerType must match the existing manager.

Response​

  • Name
    updatedManager
    Type
    Manager
    Description

    The stored draft, with sub-agent summaries hydrated.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

curl https://api.autessa.com/autessa_poweruser/managers/update \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "managerId": "mZ8kW3qN5d",
    "updatedManager": {
      "managerId": "mZ8kW3qN5d",
      "managerType": "SIMPLE",
      "name": "Customer Success Manager",
      "description": "Coordinates triage, research, and reply agents for support requests.",
      "instructions": "Delegate each request to the best agent. Escalate billing issues.",
      "model": "BIG_INSTRUCTION_FOLLOWING",
      "maxIterations": 10,
      "agents": [
        { "agentId": "V1StGXR8Z5" },
        { "agentId": "aQ6rD4xL8c" }
      ]
    }
  }'
Response (truncated)
{
  "updatedManager": {
    "managerId": "mZ8kW3qN5d",
    "managerType": "SIMPLE",
    "name": "Customer Success Manager",
    "agents": [
      { "agentId": "V1StGXR8Z5", "name": "Support Triage Agent" },
      { "agentId": "aQ6rD4xL8c", "name": "Billing Research Agent" }
    ]
  },
  "errors": []
}

Publish a manager​

POST/managers/publish

Snapshots the current draft as a new published version. Client API executions that don't pin a version always use the latest published version. The previously published version becomes archived and remains available for /rollback.

Requires PUBLISH or ADMIN access.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to publish.

Response​

  • Name
    publishedManagerVersion
    Type
    integer
    Description

    The new published version number.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/publish \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "managerId": "mZ8kW3qN5d" }'
Response
{
  "publishedManagerVersion": 2,
  "errors": []
}

Roll back a manager​

POST/managers/rollback

Republishes an archived version, making it the live published version again. The draft working copy is not changed. Use /versions to find rollback candidates.

Requires PUBLISH or ADMIN access.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to roll back.

  • Name
    versionToRollback
    Type
    integer
    Description

    The archived version number to republish.

Response​

  • Name
    newPublishedVersion
    Type
    integer
    Description

    The version number now published.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/rollback \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "managerId": "mZ8kW3qN5d", "versionToRollback": 1 }'
Response
{
  "newPublishedVersion": 3,
  "errors": []
}

List versions​

POST/managers/versions

Returns the manager's published version and all archived version numbers.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to inspect.

Response​

  • Name
    currentPublishedVersion
    Type
    integer
    Description

    The live published version, or absent if the manager was never published.

  • Name
    archivedVersions
    Type
    array<integer>
    Description

    Previously published version numbers available for rollback.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/versions \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "managerId": "mZ8kW3qN5d" }'
Response
{
  "currentPublishedVersion": 2,
  "archivedVersions": [1],
  "errors": []
}

List conversations​

POST/managers/conversations

Returns the manager's conversation history, newest first, paginated. By default sub-agent conversations are referenced by ID inside the logs; pass expandAgents: true to inline the full agent conversations.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager whose conversations to list.

  • Name
    page
    Type
    integer
    Description

    Zero-based page index. Defaults to 0.

  • Name
    includeMySandboxConversations
    Type
    boolean
    Description

    Also include the calling user's sandbox (Builder test) conversations. Defaults to false.

  • Name
    expandAgents
    Type
    boolean
    Description

    Inline each delegated agent's full conversation inside its INVOKE_AGENT_RESPONSE log entry instead of returning only the agent conversation ID. Defaults to false.

Response​

  • Name
    conversations
    Type
    array<Conversation>
    Description

    Conversation records. Each has resourceId (the manager's ID), version, conversationId, apiKeyId (or "my-sandbox"), closeDate, logs (see conversation logs), currentIteration (coordination iterations used), and an optional evaluationContext.

  • Name
    totalElements
    Type
    integer
    Description

    Total conversations across all pages.

  • Name
    totalPages
    Type
    integer
    Description

    Total number of pages.

  • Name
    currentPage
    Type
    integer
    Description

    The page returned.

  • Name
    pageSize
    Type
    integer
    Description

    Conversations per page.

  • Name
    hasNext
    Type
    boolean
    Description

    Whether another page exists.

  • Name
    hasPrevious
    Type
    boolean
    Description

    Whether a previous page exists.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

curl https://api.autessa.com/autessa_poweruser/managers/conversations \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "managerId": "mZ8kW3qN5d", "page": 0, "expandAgents": false }'
Response (truncated)
{
  "conversations": [
    {
      "resourceId": "mZ8kW3qN5d",
      "version": "2",
      "conversationId": "conv_m7f2e9c1a4",
      "apiKeyId": "key_xyz",
      "closeDate": "2026-06-30T09:15:22",
      "currentIteration": 3,
      "logs": [
        {
          "logType": "USER_INPUT",
          "combinedMultimodalInput": [
            { "inputType": "TEXT", "content": "My last invoice looks wrong." }
          ]
        },
        {
          "logType": "INVOKE_AGENT_REQUEST",
          "invokeAgentRequest": {
            "invocationId": "8f3a1c2e-...",
            "agentId": "aQ6rD4xL8c",
            "agentName": "Billing Research Agent",
            "taskDescription": "Look up the customer's latest invoice and check the line items."
          }
        },
        {
          "logType": "INVOKE_AGENT_RESPONSE",
          "invokeAgentResponse": {
            "invocationId": "8f3a1c2e-...",
            "agentId": "aQ6rD4xL8c",
            "responseType": "COMPLETE",
            "summary": "Invoice INV-1042 double-billed the June commitment."
          }
        },
        {
          "logType": "MESSAGE_TO_USER",
          "multimodalOutput": {
            "outputType": "TEXT",
            "content": "You're right — the June commitment was billed twice. I've flagged it."
          }
        }
      ],
      "evaluationContext": null
    }
  ],
  "totalElements": 42,
  "totalPages": 5,
  "currentPage": 0,
  "pageSize": 10,
  "hasNext": true,
  "hasPrevious": false,
  "errors": []
}

Conversation logs​

Each entry in logs has a logType that determines which other fields are present:

logTypePayload
USER_INPUTcombinedMultimodalInput — array of text/audio inputs from the user.
MANAGER_REASONINGmultimodalOutput — the manager's internal reasoning.
MESSAGE_TO_USERmultimodalOutput — the manager's text or audio response.
INVOKE_AGENT_REQUESTinvokeAgentRequest — invocationId, agentId, agentName, taskDescription, context, variables, and any forwarded multimodal inputs.
INVOKE_AGENT_RESPONSEinvokeAgentResponse — matching invocationId, agentId, agentName, responseType (COMPLETE or HELP), summary (for COMPLETE), helpRequest (for HELP), and the sub-agent's conversation ID (expanded inline when expandAgents is true).
USER_REQUESTuserRequest — the manager asking the user for clarification; the reply appears as userResponse.

Audio entries additionally carry playback metadata (playbackState, playbackStartedAt, playbackCompletedAt, spokenContent when a response was interrupted).

Get a conversation​

POST/managers/conversation

Fetches a single conversation by ID — unlike /conversations this is not paginated, so deep links to older conversations resolve directly.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager the conversation belongs to.

  • Name
    conversationId
    Type
    string
    Description

    The conversation to fetch.

  • Name
    expandAgents
    Type
    boolean
    Description

    Inline delegated agents' full conversations. Defaults to false.

Response​

  • Name
    conversation
    Type
    Conversation
    Description

    The conversation record, same shape as entries in /conversations.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/conversation \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "managerId": "mZ8kW3qN5d",
    "conversationId": "conv_m7f2e9c1a4",
    "expandAgents": true
  }'
Response (truncated)
{
  "conversation": {
    "resourceId": "mZ8kW3qN5d",
    "version": "2",
    "conversationId": "conv_m7f2e9c1a4",
    "currentIteration": 3,
    "logs": [ { "logType": "USER_INPUT", "combinedMultimodalInput": [] } ],
    "evaluationContext": {
      "humanEvaluation": {
        "status": "SUCCESSFUL",
        "notes": "Resolved on first contact.",
        "evaluationTime": "2026-06-30T10:02:44"
      }
    }
  },
  "errors": []
}

Get statistics​

POST/managers/statistics

Aggregated evaluation statistics for a manager, optionally windowed by date, with a per-version breakdown.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to analyze.

  • Name
    startDate
    Type
    string
    Description

    ISO-8601 date-time lower bound (for example "2026-06-01T00:00:00").

  • Name
    endDate
    Type
    string
    Description

    ISO-8601 date-time upper bound.

Response​

  • Name
    statistics
    Type
    object
    Description

    The statistics envelope.

  • Name
    statistics.totalConversations
    Type
    integer
    Description

    Conversations in the window.

  • Name
    statistics.humanEvaluation
    Type
    EvaluationStats
    Description

    Counts from human evaluations: totalEvaluated, successful, successfulNotEfficient, successfulNotAllSteps, unsuccessful.

  • Name
    statistics.automatedEvaluation
    Type
    EvaluationStats
    Description

    Same counts from automated evaluation.

  • Name
    statistics.humanPrecedenceEvaluation
    Type
    EvaluationStats
    Description

    Merged view where a human verdict overrides the automated one for the same conversation.

  • Name
    statistics.versionBreakdown
    Type
    object
    Description

    Map of version number to a per-version stats object with the same fields.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/statistics \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "managerId": "mZ8kW3qN5d",
    "startDate": "2026-06-01T00:00:00",
    "endDate": "2026-07-01T00:00:00"
  }'
Response (truncated)
{
  "statistics": {
    "totalConversations": 42,
    "humanEvaluation": {
      "totalEvaluated": 12,
      "successful": 9,
      "successfulNotEfficient": 1,
      "successfulNotAllSteps": 1,
      "unsuccessful": 1
    },
    "automatedEvaluation": {
      "totalEvaluated": 42,
      "successful": 33,
      "successfulNotEfficient": 4,
      "successfulNotAllSteps": 2,
      "unsuccessful": 3
    },
    "humanPrecedenceEvaluation": {
      "totalEvaluated": 42,
      "successful": 34,
      "successfulNotEfficient": 3,
      "successfulNotAllSteps": 2,
      "unsuccessful": 3
    },
    "versionBreakdown": {
      "2": { "totalConversations": 28 }
    }
  },
  "errors": []
}

Submit a human evaluation​

POST/managers/submit-evaluation

Attaches a human evaluation to a manager conversation. Human evaluations take precedence over automated ones in statistics. The evaluation timestamp and evaluator are set server-side from the calling user — you only supply the verdict and notes.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager the conversation belongs to.

  • Name
    conversationId
    Type
    string
    Description

    The conversation being evaluated.

  • Name
    humanEvaluation
    Type
    object
    Description

    The evaluation payload.

  • Name
    humanEvaluation.status
    Type
    string
    Description

    One of SUCCESSFUL, SUCCESSFUL_NOT_EFFICIENT, SUCCESSFUL_NOT_ALL_STEPS, UNSUCCESSFUL.

  • Name
    humanEvaluation.notes
    Type
    string
    Description

    Free-form reviewer notes.

Response​

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred (for example "Conversation not found").

cURL
curl https://api.autessa.com/autessa_poweruser/managers/submit-evaluation \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "managerId": "mZ8kW3qN5d",
    "conversationId": "conv_a1b2c3d4e5",
    "humanEvaluation": {
      "status": "SUCCESSFUL",
      "notes": "Routed to the right sub-agent and resolved on first pass."
    }
  }'
Response
{
  "errors": []
}

Delete a manager​

POST/managers/delete

Permanently deletes a manager, including its draft and version history. The sub-agents themselves are not deleted. This is destructive and cannot be undone.

Requires ADMIN access on the manager.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to delete.

Response​

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/delete \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "managerId": "mZ8kW3qN5d" }'
Response
{
  "errors": []
}

Share a manager​

POST/managers/share

Sets the manager's sharing level and per-user grants in one call.

Requires ADMIN access on the manager.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to share.

  • Name
    level
    Type
    string
    Description

    Sharing level: PRIVATE, SPECIFIC_MEMBER, or COMPANY.

  • Name
    accessLevel
    Type
    string
    Description

    When level is COMPANY, the access level every company member gets: READ, WRITE, PUBLISH, or ADMIN.

  • Name
    usersToAdd
    Type
    array<UserShare>
    Description

    Users to grant access. Each entry: userEmail or userId (string), plus accessLevel.

  • Name
    usersToRemove
    Type
    array<UserShare>
    Description

    Users whose access to revoke, same entry shape.

Response​

  • Name
    level
    Type
    string
    Description

    The resulting sharing level.

  • Name
    accessLevel
    Type
    string
    Description

    The resulting company-wide access level, when shared with the company.

  • Name
    usersWithAccess
    Type
    array<UserShare>
    Description

    The resulting per-user grants.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/share \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "managerId": "mZ8kW3qN5d",
    "level": "SPECIFIC_MEMBER",
    "usersToAdd": [
      { "userEmail": "sam@acme.com", "accessLevel": "WRITE" }
    ],
    "usersToRemove": []
  }'
Response
{
  "level": "SPECIFIC_MEMBER",
  "usersWithAccess": [
    {
      "userEmail": "sam@acme.com",
      "userId": "uB7nT2wQ9k",
      "accessLevel": "WRITE"
    }
  ],
  "errors": []
}

Get sharing details​

POST/managers/get-sharing-details

Returns the manager's current sharing configuration and the calling user's own access level.

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to inspect.

Response​

  • Name
    sharingLevel
    Type
    string
    Description

    PRIVATE, SPECIFIC_MEMBER, or COMPANY.

  • Name
    companyPermissionLevel
    Type
    string
    Description

    Access level granted company-wide, when sharingLevel is COMPANY.

  • Name
    sharedWith
    Type
    array<UserShare>
    Description

    Per-user grants: userEmail, userId, accessLevel.

  • Name
    userAccessLevel
    Type
    string
    Description

    The calling user's effective access level.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/get-sharing-details \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "managerId": "mZ8kW3qN5d" }'
Response
{
  "sharingLevel": "SPECIFIC_MEMBER",
  "companyPermissionLevel": null,
  "sharedWith": [
    {
      "userEmail": "sam@acme.com",
      "userId": "uB7nT2wQ9k",
      "accessLevel": "WRITE"
    }
  ],
  "userAccessLevel": "ADMIN",
  "errors": []
}

Transfer ownership​

POST/managers/transfer-ownership

Transfers the manager to another member of the company. Only the current owner may call this, and the new owner must already have some access to the manager (share it with them first).

Request parameters​

  • Name
    managerId
    Type
    string
    Description

    The manager to transfer.

  • Name
    newOwnerId
    Type
    string
    Description

    User ID of the new owner. Must be a member of the company with existing access to the manager.

Response​

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred (for example "New owner does not have access to manager yet.").

cURL
curl https://api.autessa.com/autessa_poweruser/managers/transfer-ownership \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "managerId": "mZ8kW3qN5d",
    "newOwnerId": "uB7nT2wQ9k"
  }'
Response
{
  "errors": []
}
POST/managers/generate-audio-upload-link

Returns a pre-signed S3 URL for uploading a WAV audio file. Upload the file with an HTTP PUT to uploadUrl, then reference the returned s3Uri wherever an audio input is accepted.

Request parameters​

None — send an empty object {} (WAV format is currently fixed).

Response​

  • Name
    uploadUrl
    Type
    string
    Description

    Pre-signed URL; PUT the file bytes here with Content-Type: audio/wav.

  • Name
    s3Uri
    Type
    string
    Description

    S3 URI to reference the uploaded file.

  • Name
    expiresInSeconds
    Type
    integer
    Description

    How long the upload URL stays valid.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/generate-audio-upload-link \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Then upload the file:
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/wav" \
  --data-binary '@recording.wav'
Response
{
  "uploadUrl": "https://s3.amazonaws.com/autessa-audio/...",
  "s3Uri": "s3://autessa-audio/company-cP2mK7dX4v/audio-8f3a.wav",
  "expiresInSeconds": 3600,
  "errors": []
}
POST/managers/generate-image-upload-link

Returns a pre-signed S3 URL for uploading an image.

Request parameters​

  • Name
    fileExtension
    Type
    string
    Description

    "png", "jpg", or "jpeg". Defaults to "png".

Response​

  • Name
    uploadUrl
    Type
    string
    Description

    Pre-signed URL; PUT the file bytes here.

  • Name
    s3Uri
    Type
    string
    Description

    S3 URI to reference the uploaded file.

  • Name
    mimeType
    Type
    string
    Description

    MIME type to send as Content-Type on the upload.

  • Name
    expiresInSeconds
    Type
    integer
    Description

    How long the upload URL stays valid.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/generate-image-upload-link \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileExtension": "png" }'
Response
{
  "uploadUrl": "https://s3.amazonaws.com/autessa-images/...",
  "s3Uri": "s3://autessa-images/company-cP2mK7dX4v/image-2b7c.png",
  "mimeType": "image/png",
  "expiresInSeconds": 3600,
  "errors": []
}
POST/managers/generate-file-upload-link

Returns a pre-signed S3 URL for uploading an arbitrary document.

Request parameters​

  • Name
    fileExtension
    Type
    string
    Description

    File extension, for example "pdf", "docx", "txt".

Response​

  • Name
    uploadUrl
    Type
    string
    Description

    Pre-signed URL; PUT the file bytes here.

  • Name
    s3Uri
    Type
    string
    Description

    S3 URI to reference the uploaded file.

  • Name
    mimeType
    Type
    string
    Description

    MIME type to send as Content-Type on the upload.

  • Name
    expiresInSeconds
    Type
    integer
    Description

    How long the upload URL stays valid.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/managers/generate-file-upload-link \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileExtension": "pdf" }'
Response
{
  "uploadUrl": "https://s3.amazonaws.com/autessa-files/...",
  "s3Uri": "s3://autessa-files/company-cP2mK7dX4v/file-9d1e.pdf",
  "mimeType": "application/pdf",
  "expiresInSeconds": 3600,
  "errors": []
}

Errors​

StatusWhen
200Success — check errors for validation messages (blank name/description on create, unknown conversation ID).
401The linked user lacks the required access level (see the access table), or is not the owner for transfer-ownership.
403Scoped key without the endpoint in its allow-list.
408Server-side error; errors contains the message.