Skip to content
Voicebot

Request user magic link

POST
/v1/user/{sid}/magic-link/request
curl --request POST \
  --url https://example.com/v1/user/example/magic-link/request \
  --header 'Authorization: Bearer <token>'

Returns a single-use magic-link token for the user, with the consume URL. Athena sends no email — the caller delivers the token to the user through its own channel; a new token invalidates the previous outstanding one. Rejected with 409 when the user is not active.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
sid
required
string

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json
object
token
required
string
expires_at
required
string format: date-time
consume_url
required

Absolute URL of the public consume endpoint the token is redeemed at.

string
Examplegenerated
{
  "token": "example",
  "expires_at": "2026-04-15T12:00:00Z",
  "consume_url": "example"
}

404

Section titled “404”

Resource does not exist

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

409

Section titled “409”

Conflict (user is not active)

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}