AgentSIM Sessions API
The Sessions API from AgentSIM — 5 operation(s) for sessions.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/agentsim-dev:agentsim-dev-sessions-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: AgentSIM Sessions API
description: Authentication challenges and runtime-bound Browser Access for apps you own. Live SMS requires account access. Email and magic-link channels accept injected test messages only; passkey and anti-bot channels record a halt.
version: 1.0.0
contact:
url: https://console.agentsim.dev
servers:
- url: https://api.agentsim.dev/v1
security:
- apiKeyAuth: []
tags:
- name: Sessions
paths:
/sessions:
post:
operationId: provisionSession
summary: Open a challenge session
description: Authentication challenges for apps you own. Normal SMS requests require verification of the exact owned public HTTPS origin in Agent control, a matching allow policy, remaining allowance, and live-line availability. Mock SMS is explicit with test_mode=mock. Email and magic-link channels accept injected test messages only; passkey and anti-bot channels record a halt.
tags:
- Sessions
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- service_url
properties:
agent_id:
type: string
description: Identifier for the agent instance. Used for grouping and metrics.
example: checkout-bot
channel:
type: string
enum:
- sms_otp
- email_otp
- magic_link
- webauthn_required
- anti_bot_gate
- browser_access
description: Challenge channel. Browser Access requires a claimed runtime bearer and DPoP proof. Defaults to SMS OTP.
default: sms_otp
example: email_otp
test_mode:
type: string
enum:
- mock
description: Optional test-only SMS mode. Valid only with channel=sms_otp. It never reserves a live carrier line.
country:
type: string
description: ISO 3166-1 alpha-2 country code. Defaults to US.
default: US
example: US
service_url:
type: string
format: uri
pattern: ^https://
description: Required public HTTPS origin of the owned service. Credentials, IP literals, unresolved hosts, and hosts resolving to non-public addresses are rejected before allocation.
example: https://staging.example.com
ttl_seconds:
type: integer
description: Session lifetime in seconds.
minimum: 60
maximum: 86400
default: 900
webhook_url:
type: string
description: HTTPS endpoint to receive OTP push notifications. Not accepted by browser_access.
example: https://your-agent.example.com/otp-hook
connection_id:
type: string
format: uuid
description: Required for browser_access.
purpose:
type: string
maxLength: 280
description: Human-readable purpose required for browser_access.
goal:
type: string
maxLength: 10000
description: Exact human-approved goal required for browser_access.
operations:
type: array
minItems: 1
maxItems: 20
uniqueItems: true
items:
type: string
description: Exact declared operations required for browser_access.
responses:
'201':
description: Challenge session opened successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
'402':
description: Live access or unused allowance required
'429':
description: Rate limited
'503':
description: Configured SMS provider pool exhausted for requested country
'400':
description: Invalid request or schema validation failed
'403':
description: Policy or plan restriction
get:
operationId: listSessions
summary: List sessions
description: Returns the authenticated account's sessions, newest first, optionally filtered by status or agent_id. Agent credentials require sessions:read and can only inspect their own sessions. The active filter excludes sessions whose expiry time has passed. Challenge secrets are not included.
tags:
- Sessions
parameters:
- name: status
in: query
schema:
type: string
enum:
- active
- completed
- expired
- failed
- name: agent_id
in: query
schema:
type: string
minLength: 1
maxLength: 128
- name: limit
in: query
schema:
type: integer
default: 20
minimum: 1
maximum: 100
- name: after
in: query
description: Last session_id from the previous page
schema:
type: string
format: uuid
responses:
'200':
description: Paginated list of sessions
content:
application/json:
schema:
type: object
properties:
sessions:
type: array
items:
$ref: '#/components/schemas/Session'
has_more:
type: boolean
/sessions/{id}/inject-email:
post:
operationId: injectEmail
summary: Submit a test email message
description: Inject an email body into an active email_otp or magic_link session. Email OTP reuses the normal OTP parser. Magic-link sessions return the first HTTP(S) URL. This endpoint does not receive SMTP email.
tags:
- Sessions
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- body
properties:
body:
type: string
minLength: 1
maxLength: 100000
example: Your AgentSIM sign-in code is 624810
responses:
'201':
description: Email body parsed
content:
application/json:
schema:
oneOf:
- type: object
required:
- channel
- inbox_address
- otp_code
- received_at
properties:
channel:
type: string
enum:
- email_otp
inbox_address:
type: string
example: sess_01HXYZ@mail.test.agentsim.dev
otp_code:
type: string
example: '624810'
confidence:
type: number
method:
type: string
received_at:
type: string
format: date-time
- type: object
required:
- channel
- inbox_address
- magic_link
- received_at
properties:
channel:
type: string
enum:
- magic_link
inbox_address:
type: string
example: sess_01HXYZ@mail.test.agentsim.dev
magic_link:
type: string
format: uri
example: https://app.example.test/auth/confirm?token=first
received_at:
type: string
format: date-time
'400':
description: Body is invalid or lacks the challenge expected by the channel
'401':
description: API key is missing or invalid
'404':
description: Session not found, unavailable to this account, or not an email challenge
'409':
description: Session is inactive or already has an injected email
'429':
description: Injection rate limit exceeded
/sessions/{id}/wait:
post:
operationId: waitForOtp
summary: Wait for a challenge result
description: Wait for the next unconsumed code or test link. Reading a code consumes it. Credential and session liveness are rechecked before each polling attempt. Halt channels return their recorded verdict immediately.
tags:
- Sessions
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
timeout_seconds:
type: integer
minimum: 1
maximum: 120
default: 60
responses:
'200':
description: Challenge received
content:
application/json:
schema:
oneOf:
- type: object
required:
- channel
- otp_code
- from_number
- message_id
- received_at
properties:
channel:
type: string
enum:
- sms_otp
otp_code:
type: string
example: '483920'
from_number:
type: string
example: '+12025550199'
message_id:
type: string
received_at:
type: string
format: date-time
- type: object
required:
- channel
- inbox_address
- otp_code
- received_at
properties:
channel:
type: string
enum:
- email_otp
inbox_address:
type: string
example: sess_01HXYZ@mail.test.agentsim.dev
otp_code:
type: string
example: '624810'
received_at:
type: string
format: date-time
- type: object
required:
- channel
- inbox_address
- magic_link
- received_at
properties:
channel:
type: string
enum:
- magic_link
inbox_address:
type: string
example: sess_01HXYZ@mail.test.agentsim.dev
magic_link:
type: string
format: uri
example: https://app.example.test/auth/confirm?token=first
received_at:
type: string
format: date-time
- type: object
required:
- channel
- verdict
- webauthn_required
- received_at
properties:
channel:
type: string
enum:
- webauthn_required
verdict:
type: string
enum:
- webauthn_required
webauthn_required:
type: boolean
enum:
- true
received_at:
type: string
format: date-time
- type: object
required:
- channel
- verdict
- anti_bot_gate
- received_at
properties:
channel:
type: string
enum:
- anti_bot_gate
verdict:
type: string
enum:
- anti_bot_gate
anti_bot_gate:
type: boolean
enum:
- true
received_at:
type: string
format: date-time
'401':
description: Agent bearer token is no longer active
'403':
description: API key has been revoked
'404':
description: Session not found
'408':
description: Challenge wait timed out
'409':
description: Session already completed or released
/sessions/{id}/messages:
get:
operationId: getMessages
summary: Get messages
description: Returns message records newest first, without raw SMS bodies. Reading parsed OTPs marks them consumed.
tags:
- Sessions
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 50
maximum: 100
- name: after
in: query
description: The next_cursor timestamp returned by the previous page
schema:
type: string
format: date-time
responses:
'200':
description: List of messages
content:
application/json:
schema:
type: object
properties:
messages:
type: array
items:
type: object
properties:
id:
type: string
from_number:
type: string
otp_code:
type:
- string
- 'null'
received_at:
type: string
format: date-time
to_number:
type: string
otp_confidence:
type:
- string
- 'null'
otp_method:
type:
- string
- 'null'
otp_consumed:
type: boolean
otp_consumed_at:
type:
- string
- 'null'
format: date-time
webhook_delivered:
type: boolean
description: Notification queued for delivery; does not prove receiver processing.
has_more:
type: boolean
next_cursor:
type:
- string
- 'null'
format: date-time
/sessions/{id}:
get:
operationId: getSession
summary: Get session status
description: Browser sessions require an agent bearer and DPoP proof and include normalized authorization and provider run status.
tags:
- Sessions
security:
- apiKeyAuth: []
- agentBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Session status
'404':
description: Session not found
delete:
security:
- apiKeyAuth: []
- agentBearer: []
operationId: releaseSession
summary: Release a session
description: Releases the phone number and closes the session. Called automatically by SDK context managers.
tags:
- Sessions
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Session released
content:
application/json:
schema:
type: object
properties:
session_id:
type: string
status:
type: string
example: completed
closed_at:
type: string
format: date-time
'404':
description: Session not found
'409':
description: Session already closed
components:
schemas:
Session:
type: object
properties:
session_id:
type: string
format: uuid
example: 01234567-89ab-4cde-8fab-0123456789ab
channel:
type: string
enum:
- sms_otp
- email_otp
- magic_link
- webauthn_required
- anti_bot_gate
- browser_access
example: sms_otp
number:
type:
- string
- 'null'
description: Phone number for an SMS OTP session.
example: '+14155550123'
inbox_address:
type:
- string
- 'null'
description: Test-only address for an email OTP or magic-link session.
example: sess_01HXYZ@mail.test.agentsim.dev
country:
type: string
example: US
agent_id:
type: string
example: checkout-bot
expires_at:
type: string
format: date-time
status:
type: string
enum:
- active
- completed
- expired
- failed
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
agentBearer:
type: http
scheme: bearer
bearerFormat: AgentSIM runtime token
description: Requires a fresh DPoP header signed by the claimed Ed25519 runtime key.