Skip to main content

Agents

Manage the full lifecycle of agents programmatically: create and configure them, publish and roll back versions, inspect conversation history, submit evaluations, and control sharing and ownership.

All paths on this page are relative to https://api.autessa.com/autessa_poweruser/agents. 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 agent object​

Agents are returned as a polymorphic object keyed on agentType. All types share the base fields; each type adds its own configuration on top.

Base fields​

  • Name
    agentId
    Type
    string
    Description

    Unique agent identifier.

  • Name
    agentType
    Type
    string
    Description

    One of SIMPLE, MCP, CRITIC, SEARCH. 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 agent does. Used by managers when deciding which agent to invoke.

  • Name
    agentInstructions
    Type
    string
    Description

    The system prompt. May contain @@{variableName}@@ placeholders that are 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.

  • 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
    enableBrowserTools
    Type
    boolean
    Description

    Whether the agent may use built-in browser tools.

Type-specific fields​

  • Name
    maxIterations
    Type
    integer
    Description

    SIMPLE, MCP, CRITIC, SEARCH — maximum reasoning/tool loop iterations per turn (default 10).

  • Name
    tools
    Type
    array<Tool>
    Description

    SIMPLE, CRITIC, SEARCH — tools attached to the agent. See Tools.

  • Name
    mcpServerId
    Type
    string
    Description

    MCP — the MCP server whose tools the agent uses.

  • Name
    autessaDbTableId
    Type
    string
    Description

    SEARCH — the AutessaDB table to search.

  • Name
    searchColumnName
    Type
    string
    Description

    SEARCH — the column that is semantically indexed.

  • Name
    topK
    Type
    integer
    Description

    SEARCH — number of results to retrieve (default 5).

  • Name
    scoreThreshold
    Type
    number
    Description

    SEARCH — minimum similarity score (default 0.7).

  • Name
    goodCriteria
    Type
    array<string>
    Description

    CRITIC — criteria a response must satisfy.

  • Name
    badCriteria
    Type
    array<string>
    Description

    CRITIC — criteria a response must avoid.

  • Name
    maxCriticIterations
    Type
    integer
    Description

    CRITIC — max revise-and-recheck rounds (default 3).

  • Name
    criticModel
    Type
    string
    Description

    CRITIC — model alias used by the critic pass.

  • Name
    streamCriticFeedback
    Type
    boolean
    Description

    CRITIC — whether critic feedback is streamed to the caller.

  • Name
    criticContextExchanges
    Type
    integer
    Description

    CRITIC — how many prior exchanges the critic sees (default 3).

Agent object (SIMPLE)
{
  "agentId": "V1StGXR8Z5",
  "agentType": "SIMPLE",
  "name": "Support Triage Agent",
  "description": "Classifies inbound support tickets and drafts replies.",
  "agentInstructions": "You are a support triage specialist for @@{companyName}@@ ...",
  "model": "BIG_INSTRUCTION_FOLLOWING",
  "voiceConfig": {
    "voiceModel": "SMALL",
    "voiceName": "FEMALE"
  },
  "promptTemplateVariables": {
    "companyName": {
      "description": "Company the agent represents",
      "isRequired": true,
      "argumentSchema": { "type": "string" }
    }
  },
  "evaluationNotes": "A good response classifies the ticket and drafts a reply.",
  "lastPublishedTime": "2026-06-28T17:42:10",
  "tags": ["support"],
  "enableBrowserTools": false,
  "maxIterations": 10,
  "tools": [
    {
      "toolId": "kZ3mQ9pW2x",
      "name": "LookupOrder",
      "description": "Looks up an order by ID in AutessaDB."
    }
  ]
}

Versioning and access levels​

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

  • Draft — /update always edits the draft working copy. Draft changes are never visible to executions that use the published version.
  • 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 agent (the poweruser key acts as its linked user):

OperationRequired access
get, all, versions, conversations/*, statisticsAny access (READ or higher)
updateWRITE, PUBLISH, or ADMIN
publish, rollbackPUBLISH or ADMIN
delete, shareADMIN
transfer-ownershipOwner only

Create an agent​

POST/agents/create

Creates a new agent as a draft. agentName and agentDescription are both required — creation fails with an error message if either is blank. Configure instructions, model, and tools afterwards with /update, then /publish to make it executable.

Request parameters​

  • Name
    agentType
    Type
    string
    Description

    SIMPLE, MCP, CRITIC, or SEARCH.

  • Name
    agentName
    Type
    string
    Description

    Display name. Must be non-blank.

  • Name
    agentDescription
    Type
    string
    Description

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

  • Name
    mcpServerId
    Type
    string
    Description

    MCP agents only — the MCP server to bind.

  • Name
    autessaDbTableId
    Type
    string
    Description

    SEARCH agents only — the AutessaDB table to search.

  • Name
    searchColumnName
    Type
    string
    Description

    SEARCH agents only — the indexed column to search over.

  • Name
    topK
    Type
    integer
    Description

    SEARCH agents only — number of results to retrieve.

  • Name
    scoreThreshold
    Type
    number
    Description

    SEARCH agents only — minimum similarity score.

  • Name
    enableAutoContext
    Type
    boolean
    Description

    SEARCH agents only — automatically inject retrieved context.

Response​

  • Name
    agent
    Type
    Agent
    Description

    The newly created agent object.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

curl https://api.autessa.com/autessa_poweruser/agents/create \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentType": "SIMPLE",
    "agentName": "Support Triage Agent",
    "agentDescription": "Classifies inbound support tickets and drafts replies."
  }'
Response
{
  "agent": {
    "agentId": "V1StGXR8Z5",
    "agentType": "SIMPLE",
    "name": "Support Triage Agent",
    "description": "Classifies inbound support tickets and drafts replies.",
    "agentInstructions": "You are a professional agent who does as asked.",
    "model": "SMALL_INSTRUCTION_FOLLOWING",
    "maxIterations": 10,
    "tools": []
  },
  "errors": []
}

Get an agent​

POST/agents/get

Retrieves an agent's full configuration. Without a version parameter you get the current draft working copy; pass version to read a specific published or archived snapshot.

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent to fetch.

  • Name
    version
    Type
    object
    Description

    Optional version selector: versionState (PUBLISHED, DRAFT, or ARCHIVED; defaults to PUBLISHED when the object is present) and an optional versionNumber.

Response​

  • Name
    agent
    Type
    Agent
    Description

    The agent object.

  • Name
    permission
    Type
    string
    Description

    The calling user's access level on this agent: 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/agents/get \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "V1StGXR8Z5",
    "version": { "versionState": "PUBLISHED" }
  }'
Response (truncated)
{
  "agent": {
    "agentId": "V1StGXR8Z5",
    "agentType": "SIMPLE",
    "name": "Support Triage Agent",
    "model": "BIG_INSTRUCTION_FOLLOWING",
    "maxIterations": 10,
    "tools": [{ "toolId": "kZ3mQ9pW2x", "name": "LookupOrder" }]
  },
  "permission": "ADMIN",
  "voiceOptionsList": [
    {
      "voiceModel": "SMALL",
      "voices": {
        "builtInVoiceNames": ["FEMALE", "MALE"],
        "customVoiceNames": []
      }
    }
  ],
  "errors": []
}

List all agents​

POST/agents/all

Lists every agent 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
    ownedAgents
    Type
    array<Agent>
    Description

    Agents the linked user owns.

  • Name
    companySharedAgents
    Type
    array<Agent>
    Description

    Agents shared with the whole company.

  • Name
    sharedWithMeAgents
    Type
    array<Agent>
    Description

    Agents 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/agents/all \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "ownedAgents": [
    {
      "agentId": "V1StGXR8Z5",
      "agentType": "SIMPLE",
      "name": "Support Triage Agent",
      "description": "Classifies inbound support tickets and drafts replies.",
      "tags": ["support"],
      "lastPublishedTime": "2026-06-28T17:42:10"
    }
  ],
  "companySharedAgents": [],
  "sharedWithMeAgents": [],
  "errors": []
}

Update an agent​

POST/agents/update

Replaces the agent's draft configuration with updatedAgent. This is a whole-object update: fetch the draft with /get, modify it, and send the full object back. Published versions are unaffected until you /publish.

Requires WRITE, PUBLISH, or ADMIN access.

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent to update.

  • Name
    updatedAgent
    Type
    Agent
    Description

    The complete agent object to store as the new draft. Uses the agent object shape; agentType must match the existing agent.

Response​

  • Name
    updatedAgent
    Type
    Agent
    Description

    The stored draft.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

curl https://api.autessa.com/autessa_poweruser/agents/update \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "V1StGXR8Z5",
    "updatedAgent": {
      "agentId": "V1StGXR8Z5",
      "agentType": "SIMPLE",
      "name": "Support Triage Agent",
      "description": "Classifies inbound support tickets and drafts replies.",
      "agentInstructions": "You are a support triage specialist. Classify each ticket ...",
      "model": "BIG_INSTRUCTION_FOLLOWING",
      "maxIterations": 10,
      "tools": [{ "toolId": "kZ3mQ9pW2x" }]
    }
  }'
Response (truncated)
{
  "updatedAgent": {
    "agentId": "V1StGXR8Z5",
    "agentType": "SIMPLE",
    "name": "Support Triage Agent",
    "model": "BIG_INSTRUCTION_FOLLOWING"
  },
  "errors": []
}

Publish an agent​

POST/agents/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
    agentId
    Type
    string
    Description

    The agent to publish.

Response​

  • Name
    publishedAgentVersion
    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/agents/publish \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "V1StGXR8Z5" }'
Response
{
  "publishedAgentVersion": 4,
  "errors": []
}

Roll back an agent​

POST/agents/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
    agentId
    Type
    string
    Description

    The agent 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/agents/rollback \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "V1StGXR8Z5", "versionToRollback": 3 }'
Response
{
  "newPublishedVersion": 5,
  "errors": []
}

List versions​

POST/agents/versions

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

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent to inspect.

Response​

  • Name
    currentPublishedVersion
    Type
    integer
    Description

    The live published version, or absent if the agent 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/agents/versions \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "V1StGXR8Z5" }'
Response
{
  "currentPublishedVersion": 4,
  "archivedVersions": [1, 2, 3],
  "errors": []
}

List conversations​

POST/agents/conversations/history

Returns the agent's conversation history, newest first, paginated.

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent 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.

Response​

  • Name
    conversations
    Type
    array<Conversation>
    Description

    Conversation records. Each has resourceId (the agent's ID), version, conversationId, apiKeyId, closeDate, logs (see conversation logs), 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/agents/conversations/history \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "V1StGXR8Z5", "page": 0 }'
Response (truncated)
{
  "conversations": [
    {
      "resourceId": "V1StGXR8Z5",
      "version": "4",
      "conversationId": "conv_a1b2c3d4e5",
      "apiKeyId": "key_xyz",
      "closeDate": "2026-06-30T09:15:22",
      "logs": [
        {
          "logType": "USER",
          "userMultimodalInputs": [
            { "inputType": "TEXT", "content": "My order is late." }
          ]
        },
        {
          "logType": "MESSAGE_TO_USER",
          "multimodalOutput": {
            "outputType": "TEXT",
            "content": "I'm sorry to hear that — let me look it up."
          }
        }
      ],
      "evaluationContext": null
    }
  ],
  "totalElements": 128,
  "totalPages": 13,
  "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
USERuserMultimodalInputs — array of text/audio inputs from the user.
MESSAGE_TO_USERmultimodalOutput — the agent's text or audio response.
TOOL_REQUESTexecuteToolRequest — toolCallId, tool name, and variables.
TOOL_RESPONSEexecuteToolResponse — toolCallId, toolName, and the tool's result.

Audio entries additionally carry playback metadata (playbackState, playbackStartedAt, playbackCompletedAt, spokenContent when a response was interrupted), and CRITIC agents can emit rejected-message entries with criticEvaluation and criticAttemptNumber.

Get a conversation​

POST/agents/conversations/conversation

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

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent the conversation belongs to.

  • Name
    conversationId
    Type
    string
    Description

    The conversation to fetch.

Response​

  • Name
    conversation
    Type
    Conversation
    Description

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

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/agents/conversations/conversation \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "V1StGXR8Z5",
    "conversationId": "conv_a1b2c3d4e5"
  }'
Response (truncated)
{
  "conversation": {
    "resourceId": "V1StGXR8Z5",
    "version": "4",
    "conversationId": "conv_a1b2c3d4e5",
    "logs": [ { "logType": "USER", "userMultimodalInputs": [] } ],
    "evaluationContext": {
      "humanEvaluation": {
        "status": "SUCCESSFUL",
        "notes": "Resolved on first contact.",
        "evaluationTime": "2026-06-30T10:02:44"
      }
    }
  },
  "errors": []
}

Submit a human evaluation​

POST/agents/submit-evaluation

Attaches a human evaluation to a 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
    agentId
    Type
    string
    Description

    The agent 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/agents/submit-evaluation \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "V1StGXR8Z5",
    "conversationId": "conv_a1b2c3d4e5",
    "humanEvaluation": {
      "status": "SUCCESSFUL",
      "notes": "Resolved on first contact."
    }
  }'
Response
{
  "errors": []
}

Get statistics​

POST/agents/statistics

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

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent 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 four fields.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/agents/statistics \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "V1StGXR8Z5",
    "startDate": "2026-06-01T00:00:00",
    "endDate": "2026-07-01T00:00:00"
  }'
Response (truncated)
{
  "statistics": {
    "totalConversations": 128,
    "humanEvaluation": {
      "totalEvaluated": 40,
      "successful": 31,
      "successfulNotEfficient": 4,
      "successfulNotAllSteps": 2,
      "unsuccessful": 3
    },
    "automatedEvaluation": {
      "totalEvaluated": 128,
      "successful": 97,
      "successfulNotEfficient": 12,
      "successfulNotAllSteps": 8,
      "unsuccessful": 11
    },
    "humanPrecedenceEvaluation": {
      "totalEvaluated": 128,
      "successful": 99,
      "successfulNotEfficient": 11,
      "successfulNotAllSteps": 8,
      "unsuccessful": 10
    },
    "versionBreakdown": {
      "4": { "totalConversations": 74 }
    }
  },
  "errors": []
}

Delete an agent​

POST/agents/delete

Permanently deletes an agent, including its draft and version history. This is destructive and cannot be undone.

Requires ADMIN access on the agent.

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent to delete.

Response​

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

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

Share an agent​

POST/agents/share

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

Requires ADMIN access on the agent.

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent 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/agents/share \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "V1StGXR8Z5",
    "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/agents/get-sharing-details

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

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent 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/agents/get-sharing-details \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "V1StGXR8Z5" }'
Response
{
  "sharingLevel": "SPECIFIC_MEMBER",
  "companyPermissionLevel": null,
  "sharedWith": [
    {
      "userEmail": "sam@acme.com",
      "userId": "uB7nT2wQ9k",
      "accessLevel": "WRITE"
    }
  ],
  "userAccessLevel": "ADMIN",
  "errors": []
}

Transfer ownership​

POST/agents/transfer-ownership

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

Request parameters​

  • Name
    agentId
    Type
    string
    Description

    The agent 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 agent.

Response​

  • Name
    errors
    Type
    array<string>
    Description

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

cURL
curl https://api.autessa.com/autessa_poweruser/agents/transfer-ownership \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "V1StGXR8Z5",
    "newOwnerId": "uB7nT2wQ9k"
  }'
Response
{
  "errors": []
}
POST/agents/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/agents/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/agents/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/agents/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/agents/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/agents/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, missing versionToRollback, conversation not found).
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.