Roark Simulation Environment API
The Simulation Environment API from Roark — 2 operation(s) for simulation environment.
The Simulation Environment API from Roark — 2 operation(s) for simulation environment.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/roark:roark-simulation-environment-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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: 3.2.0
info:
title: Roark Analytics Simulation Environment API
description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
version: 1.0.0
servers:
- description: Production
url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Simulation Environment
paths:
/v1/simulation/environment:
get:
responses:
'200':
description: List of environments
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnvironmentsResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: getV1SimulationEnvironment
tags:
- Simulation Environment
summary: List environments
description: 'Returns a paginated list of environments: the project''s own plus the environments Roark curates and shares across every project. Reference one by id when setting a customer flow variant''s environment.'
parameters:
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 50
default: 20
- in: query
name: after
schema:
type: string
post:
responses:
'201':
description: The created environment
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/EnvironmentResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: postV1SimulationEnvironment
tags:
- Simulation Environment
summary: Create an environment
description: 'Creates an environment for the project: a noise bed and the level it plays at. Reference it by id when setting a customer flow variant''s environment. Roark''s curated presets always play at the default level, so this is how a project gets the same bed louder or quieter.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentInput'
/v1/simulation/environment/{environmentId}:
get:
responses:
'200':
description: The requested environment
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/EnvironmentResponse'
required:
- data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Not found error
example:
type: not_found
code: resource_not_found
message: The requested resource could not be found
description: Not Found
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: getV1SimulationEnvironmentByEnvironmentId
tags:
- Simulation Environment
summary: Get environment by ID
description: Returns a single environment by its ID.
parameters:
- in: path
name: environmentId
schema:
type: string
format: uuid
required: true
put:
responses:
'200':
description: The updated environment
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/EnvironmentResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Not found error
example:
type: not_found
code: resource_not_found
message: The requested resource could not be found
description: Not Found
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: putV1SimulationEnvironmentByEnvironmentId
tags:
- Simulation Environment
summary: Update an environment
description: Updates one of the project's environments. Only the fields sent are changed. Runs already built keep the snapshot they were built with. Roark-curated environments cannot be edited (403).
parameters:
- in: path
name: environmentId
schema:
type: string
format: uuid
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEnvironmentInput'
delete:
responses:
'200':
description: The environment was deleted
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/DeleteEnvironmentResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Not found error
example:
type: not_found
code: resource_not_found
message: The requested resource could not be found
description: Not Found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Conflict error
example:
type: conflict
code: resource_in_use
message: The resource is in use and cannot be deleted
description: Conflict
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: deleteV1SimulationEnvironmentByEnvironmentId
tags:
- Simulation Environment
summary: Delete an environment
description: 'Soft-deletes one of the project''s environments. It disappears from reads and cannot be picked for new runs; runs already built keep their snapshot. Refused (409) while a live customer flow variant still uses it: move those variants first. Roark-curated environments cannot be deleted (403).'
parameters:
- in: path
name: environmentId
schema:
type: string
format: uuid
required: true
components:
schemas:
EnvironmentResponse:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
minLength: 1
description:
type:
- string
- 'null'
backgroundNoise:
type: string
enum:
- NONE
- AIRPORT
- CHILDREN_PLAYING
- CITY
- COFFEE_SHOP
- CONSTRUCTION
- CRYING_BABY
- DRIVING
- LIBRARY
- OFFICE
- THUNDERSTORM
- TRAIN
default: NONE
backgroundNoiseVolume:
type: number
minimum: 0
maximum: 1
default: 0.1
createdAt:
type: string
description: Creation timestamp in ISO 8601 format
updatedAt:
type: string
description: Last update timestamp in ISO 8601 format
required:
- id
- name
- backgroundNoise
- backgroundNoiseVolume
- createdAt
- updatedAt
description: 'A simulation environment: the ambient conditions a customer flow variant runs under. The list includes both your own and the ones Roark curates for every project.'
DeleteEnvironmentResponse:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the deleted environment
deleted:
type: boolean
const: true
description: Always true when the environment was deleted
required:
- id
- deleted
ErrorResponse:
type: object
properties:
type:
type: string
enum:
- validation
- authentication
- forbidden
- not_found
- conflict
- payment_required
- rate_limit
- internal
description: The error type category
examples:
- validation
- authentication
code:
type: string
description: Machine-readable error code identifier
examples:
- invalid_parameter
- missing_required_field
- unauthorized
message:
type: string
description: Human-readable error message
examples:
- The request was invalid
- Authentication required
param:
type: string
description: The parameter that caused the error (if applicable)
examples:
- email
- user_id
details:
description: Additional error context information
required:
- type
- code
- message
GetEnvironmentsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EnvironmentResponse'
pagination:
type: object
properties:
total:
type: number
description: Total number of items
hasMore:
type: boolean
description: Whether there are more items to fetch
nextCursor:
type:
- string
- 'null'
description: Cursor for the next page of items
required:
- total
- hasMore
- nextCursor
required:
- data
- pagination
description: 'Paginated list of environments: the project''s own plus the shared Roark-curated ones'
CreateEnvironmentInput:
type: object
properties:
name:
type: string
minLength: 1
description: Display name, shown wherever a flow variant references the environment
example: Busy call centre
description:
type:
- string
- 'null'
description: Optional note on when to use this environment
example: Open-plan office at peak hours
backgroundNoise:
type: string
enum:
- NONE
- AIRPORT
- CHILDREN_PLAYING
- CITY
- COFFEE_SHOP
- CONSTRUCTION
- CRYING_BABY
- DRIVING
- LIBRARY
- OFFICE
- THUNDERSTORM
- TRAIN
description: The noise bed played underneath the simulated caller. NONE plays nothing.
example: OFFICE
backgroundNoiseVolume:
type: number
minimum: 0
maximum: 1
default: 0.1
description: How loud the bed plays, as a gain from 0 (silent) to 1 (as loud as the caller). Defaults to 0.1, which sits well under the caller. Ignored on Vapi endpoints, which have no level control.
example: 0.3
required:
- name
- backgroundNoise
description: Input for creating an environment
UpdateEnvironmentInput:
type: object
properties:
name:
type: string
minLength: 1
description: Display name, shown wherever a flow variant references the environment
example: Busy call centre
description:
type:
- string
- 'null'
description: Optional note on when to use this environment
example: Open-plan office at peak hours
backgroundNoise:
type: string
enum:
- NONE
- AIRPORT
- CHILDREN_PLAYING
- CITY
- COFFEE_SHOP
- CONSTRUCTION
- CRYING_BABY
- DRIVING
- LIBRARY
- OFFICE
- THUNDERSTORM
- TRAIN
description: The noise bed played underneath the simulated caller. NONE plays nothing.
example: OFFICE
backgroundNoiseVolume:
type: number
minimum: 0
maximum: 1
default: 0.1
description: How loud the bed plays, as a gain from 0 (silent) to 1 (as loud as the caller). Defaults to 0.1, which sits well under the caller. Ignored on Vapi endpoints, which have no level control.
example: 0.3
description: Input for updating an environment. Only the fields sent are changed. Roark-curated environments cannot be edited.
securitySchemes:
Bearer:
type: http
scheme: bearer
bearerFormat: JWT