logo
API docs by Redocly

Roboto REST API (1.0.0)

Download OpenAPI specification:Download

Create, read, update, and delete Roboto resources over HTTP. This API is used by both the Roboto web application and the Roboto SDK.

actions

Create, read, and modify entities within Roboto's 'actions' domain

create_action

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
ComputeRequirements (object) or null
Default: null
ContainerParameters (object) or null
Default: null
Description (string) or Description (null) (Description)
Default: null
ActionReference (object) or null
Default: null
object (Metadata)
Array of objects (Parameters)
Requires Downloaded Inputs (boolean) or Requires Downloaded Inputs (null) (Requires Downloaded Inputs)
Default: null
Short Description (string) or Short Description (null) (Short Description)
Default: null
tags
Array of strings (Tags)
Timeout (integer) or Timeout (null) (Timeout)
Default: null
Uri (string) or Uri (null) (Uri)
Default: null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "compute_requirements": null,
  • "container_parameters": null,
  • "description": null,
  • "inherits": null,
  • "metadata": { },
  • "parameters": [
    ],
  • "requires_downloaded_inputs": null,
  • "short_description": null,
  • "tags": [
    ],
  • "timeout": null,
  • "uri": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_action

Access control

  • requires_resource_owner_unchecked
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
name
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_action

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
ComputeRequirements (object) or Compute Requirements (null) or Compute Requirements (null) (Compute Requirements)
ContainerParameters (object) or Container Parameters (null) or Container Parameters (null) (Container Parameters)
Description (string) or Description (null) or Description (null) (Description)
ActionReference (object) or Inherits (null) or Inherits (null) (Inherits)
MetadataChangeset (object) or Metadata Changeset (null) (Metadata Changeset)
ActionParameterChangeset (object) or Parameter Changeset (null) (Parameter Changeset)
Uri (string) or Uri (null) or Uri (null) (Uri)
Short Description (string) or Short Description (null) or Short Description (null) (Short Description)
Timeout (integer) or Timeout (null) or Timeout (null) (Timeout)
Requires Downloaded Inputs (boolean) or Requires Downloaded Inputs (null) (Requires Downloaded Inputs)

Responses

Request samples

Content type
application/json
{
  • "compute_requirements": {
    },
  • "container_parameters": {
    },
  • "description": "string",
  • "inherits": {
    },
  • "metadata_changeset": {
    },
  • "parameter_changeset": {
    },
  • "uri": "string",
  • "short_description": "string",
  • "timeout": 0,
  • "requires_downloaded_inputs": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_action

Access control

  • requires_resource_owner
  • deny_actions
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

set_action_accessibility

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
accessibility
required
string (Accessibility)
Enum: "organization" "action_hub"

Controls who can query for and invoke an action.

Accessibility levels determine the visibility and usability of actions within the Roboto platform. Actions can be private to an organization or published publicly in the Action Hub.

Future accessibility levels may include: "user" and/or "team".

Digest (string) or Digest (null) (Digest)
Default: null

Responses

Request samples

Content type
application/json
{
  • "accessibility": "organization",
  • "digest": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

invoke

Access control

  • requires_org
  • requires_resource_owner_unchecked
  • deny_actions
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
name
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
ComputeRequirements (object) or null
Default: null
ContainerParameters (object) or null
Default: null
data_source_id
required
string (Data Source Id)
data_source_type
required
string (InvocationDataSourceType)
Value: "Dataset"

Source of data for an action's input binding.

Defines the type of data source that provides input data to an action invocation. Currently supports datasets, with potential for future expansion to other data source types.

Idempotency Id (string) or Idempotency Id (null) (Idempotency Id)
Default: null
input_data
required
Array of strings (Input Data)
InvocationInput (object) or null
Default: null
invocation_source
required
string (InvocationSource)
Enum: "Trigger" "Manual"

Method by which an invocation was run

Invocation Source Id (string) or Invocation Source Id (null) (Invocation Source Id)
Default: null
Parameter Values (object) or Parameter Values (null) (Parameter Values)
Default: null
Timeout (integer) or Timeout (null) (Timeout)
Default: null
InvocationUploadDestination (object) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "compute_requirement_overrides": null,
  • "container_parameter_overrides": null,
  • "data_source_id": "string",
  • "data_source_type": "Dataset",
  • "idempotency_id": null,
  • "input_data": [
    ],
  • "rich_input_data": null,
  • "invocation_source": "Trigger",
  • "invocation_source_id": null,
  • "parameter_values": null,
  • "timeout": null,
  • "upload_destination": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_distinct_action_tags_for_org

List the distinct tags on the caller org's actions, for the tag filter on the org Actions page.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_distinct_action_tags_for_actionhub

List the distinct tags on Action Hub-listed actions, for the tag filter on the Action Hub page.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_invocation_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
invocation_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

cancel_invocation

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
invocation_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

set_invocation_container_info

Access control

  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
invocation_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
image_digest
required
string (Image Digest)

Responses

Request samples

Content type
application/json
{
  • "image_digest": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_invocation_ecs_task_info

Access control

  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
invocation_id
required
string
query Parameters
required
string or null
required
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

heartbeat_invocation

Access control

  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
invocation_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_invocation_ecs_logger_creds

Access control

  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
invocation_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

get_invocation_logs

Paginated logs for an invocation that has finished running. To stream logs for an invocation that has not finished running, use the /.../logs/stream endpoint.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
invocation_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_invocation_logs_location

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
invocation_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
bucket
required
string (Bucket)
prefix
required
string (Prefix)

Responses

Request samples

Content type
application/json
{
  • "bucket": "string",
  • "prefix": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

stream_invocation_logs

Stream of logs for an invocation that has not finished running.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
invocation_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_invocation_status

Access control

  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
invocation_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
status
required
integer (InvocationStatus)
Enum: 0 1 2 3 4 5 997 998 999

Invocation status enum

detail
required
string (Detail)

Responses

Request samples

Content type
application/json
{
  • "status": 0,
  • "detail": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_invocation_activity

Bucket what the caller's org's invocations were doing across a window of time.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
start_time
required
string <date-time> (Start Time)
end_time
required
string <date-time> (End Time)
ActivityPeriod (string) or null
Default: null
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null

Responses

Request samples

Content type
application/json
{
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "period": null,
  • "condition": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_invocation_breakdown

Group the caller's org's invocations currently in the given statuses along one or more dimensions.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
statuses
required
Array of integers (Statuses) non-empty
Items Enum: 0 1 2 3 4 5 997 998 999
group_by
required
Array of strings (Group By) non-empty
Items Enum: "action" "source" "submitter"
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit) [ 1 .. 100 ]
Default: 20

Responses

Request samples

Content type
application/json
{
  • "statuses": [
    ],
  • "group_by": [
    ],
  • "condition": null,
  • "limit": 20
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

batch_cancel_all_active_invocations_for_org

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Created Before (string) or Created Before (null) (Created Before)
Default: null

Responses

Request samples

Content type
application/json
{
  • "created_before": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_invocation_stats_for_org

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
start_time
required
string <date-time>

ISO 8601 datetime string

end_time
required
string <date-time>

ISO 8601 datetime string

header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

query_invocations

Access control

  • requires_resource_owner_or_admin
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_invocation_queue_stats

How deep the caller's invocation queue is, and how long it is likely to take to drain.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_scheduling_stats

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_action_metadata_keys_for_org

List the distinct top-level metadata keys on the resource owner org's actions.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

query_actions

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

query_actions_on_action_hub

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_action_tags_for_org

List the distinct tags on the resource owner org's actions.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

admin

Create, read, and modify entities within Roboto's 'admin' domain

get_admin_chats

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
query Parameters
string or null
string or null
string or null
boolean or null
string or null
limit
number
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_migrations

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_per_action_invocation_stats

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
query Parameters
start_time
number
end_time
number
limit
number
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

ai

Create, read, and modify entities within Roboto's 'ai' domain

list_agents

List agents in the caller's org, newest first.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_agent

Create a new agent for the caller's org.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
Description (string) or Description (null) (Description)
Default: null
required
object (StartAgentThreadRequest)

Request payload for starting a new agent thread.

Contains the initial messages and configuration for creating a new conversation.

Array of objects (Variables)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": null,
  • "request_template": {
    },
  • "variables": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_agent

Fetch a single agent by id.

agent_id is platform-unique, so the route does not require the caller to pass an org header — the agent record carries its own org_id and the authorization check happens inline against it.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
agent_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_agent

Patch an existing agent with the fields set on the request.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
agent_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Name (string) or Name (null) (Name)
Description (string) or Description (null) or Description (null) (Description)
StartAgentThreadRequest (object) or Request Template (null) (Request Template)
Array of Variables (objects) or Variables (null) (Variables)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "request_template": {
    },
  • "variables": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_agent

Delete an agent by id.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
agent_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

launch_agent

Resolve an agent into a thread and start it via the same code path as POST /threads.

The thread's visibility comes from request.visibility (ORG by default, since agents exist to share work), and created_from_agent_id is stamped so the agent's detail page can list "threads launched from here". The resulting thread is created in the agent's owning org — the caller's own org context (if different) is not used.

Access control

  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
agent_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
object (Values)
visibility
string (ThreadVisibility)
Default: "org"
Enum: "private" "org"

Read-scope for an :class:AgentThreadRecord.

Set when the thread is created, and changed afterwards only by the thread's creator, via :meth:roboto.ai.agent_thread.AgentThread.set_visibility (POST /v1/ai/threads/<thread_id>/visibility). Roboto admins read every thread but cannot re-scope one they did not create.

Import as :class:roboto.ai.agent_thread.ThreadVisibility.

AnalysisScope (object) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "values": {
    },
  • "visibility": "private",
  • "analysis_scope": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_agent_by_name

Fetch an agent by its (org_id, name) handle.

Mirrors :meth:Action.from_name: name + owning org are jointly unique (enforced by the agents_unique_org_name constraint from chats_018), so a name plus the resource-owner org always addresses at most one agent. The dedicated /name/ subpath avoids collision with /agents/<agent_id> for agent ids that happen to look like names. Unlike :func:get_agent (which derives the org from the looked-up record), name lookup needs the org up-front, so it goes through the X-Roboto-Resource-Owner-Id header via REQUIRES_OWNER_ORG.

Agent names are free text, so the path segment arrives percent-encoded and has to be decoded before it can match a stored name. API Gateway hands the proxy path through verbatim -- without this, an agent named "Food Preference User Triage" is looked up as Food%20Preference%20User%20Triage and always 404s.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_threads_for_user_legacy

Return the caller's own threads in their current org context, plus org-visible threads they have pinned.

A user who belongs to several orgs gets one org's threads per request, not a merged list across orgs.

Rows sort by pin time first, most recently pinned at the top of the pinned block, then by thread creation time. A pinned thread the caller did not create stays behind a visibility check, so it drops out once its creator un-shares it.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_thread_by_id_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
thread_id
required
string
query Parameters
load_messages
boolean
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_thread_delta_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
thread_id
required
string
query Parameters
next_token
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

send_message_to_thread_legacy

Access control

  • requires_org
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
thread_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
ClientViewingContext (object) or null
Default: null
AgentMessage (object) or null
Default: null
Array of Client Tools (objects) or Client Tools (null) (Client Tools)
Default: null
AnalysisScope (object) or null
Default: null
Array of Goals (any) or Goals (null) (Goals)
Default: null
Array of objects (Invoke Skills)

Responses

Request samples

Content type
application/json
{
  • "client_context": null,
  • "message": null,
  • "client_tools": null,
  • "analysis_scope": null,
  • "goals": null,
  • "invoke_skills": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null
}

get_tool_details_by_id_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
thread_id
required
string
tool_use_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

search_threads_legacy

Search agent threads the caller is allowed to read.

The repo enforces a filter whitelist (thread_id, title, created, created_by, status, visibility, created_from_agent_id, subject_id) and a sort whitelist (created). status accepts the lowercase AgentThreadStatus values (not_started, user_turn, roboto_turn, client_tool_turn, goals_failed); visibility accepts the lowercase ThreadVisibility values (private, org).

Two structural authz gates are bound from caller identity and AND-ed onto every query — both are unreachable from the request body:

  • org_id pins the result set to the caller's org.
  • visibility = 'org' OR created_by = caller_user_id hides PRIVATE threads created by other users; the caller sees every ORG-visible thread plus their own private rows. Admins (identity.is_roboto_admin) bypass this gate so the admin thread explorer continues to see every thread in an org — mirroring the per-row check in get_thread_by_id_with_access_check.

Common UI compositions: the dataset-detail "Agent Threads" tab pins subject_id == <dataset_id> as a scope filter; the agent detail page's "threads launched from this agent" list passes created_from_agent_id == <id>.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_threads_for_user

Return the caller's own threads in their current org context, plus org-visible threads they have pinned.

A user who belongs to several orgs gets one org's threads per request, not a merged list across orgs.

Rows sort by pin time first, most recently pinned at the top of the pinned block, then by thread creation time. A pinned thread the caller did not create stays behind a visibility check, so it drops out once its creator un-shares it.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

start_thread

Access control

  • requires_org
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
ClientViewingContext (object) or null
Default: null
Array of objects (Messages)
System Prompt (string) or System Prompt (null) (System Prompt)
Default: null
Array of Client Tools (objects) or Client Tools (null) (Client Tools)
Default: null
Model Profile (string) or Model Profile (null) (Model Profile)
Default: null
AnalysisScope (object) or null
Default: null
Array of Goals (any) or Goals (null) (Goals)
Default: null
Array of objects (Invoke Skills)
Array of Available Skills (objects) or Available Skills (null) (Available Skills)
Default: null
visibility
string (ThreadVisibility)
Default: "private"
Enum: "private" "org"

Read-scope for an :class:AgentThreadRecord.

Set when the thread is created, and changed afterwards only by the thread's creator, via :meth:roboto.ai.agent_thread.AgentThread.set_visibility (POST /v1/ai/threads/<thread_id>/visibility). Roboto admins read every thread but cannot re-scope one they did not create.

Import as :class:roboto.ai.agent_thread.ThreadVisibility.

Responses

Request samples

Content type
application/json
{
  • "client_context": null,
  • "messages": [
    ],
  • "system_prompt": null,
  • "client_tools": null,
  • "model_profile": null,
  • "analysis_scope": null,
  • "goals": null,
  • "invoke_skills": [
    ],
  • "available_skills": null,
  • "visibility": "private"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_thread_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
thread_id
required
string
query Parameters
load_messages
boolean
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_thread_delta

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
thread_id
required
string
query Parameters
next_token
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

send_message_to_thread

Access control

  • requires_org
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
thread_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
ClientViewingContext (object) or null
Default: null
AgentMessage (object) or null
Default: null
Array of Client Tools (objects) or Client Tools (null) (Client Tools)
Default: null
AnalysisScope (object) or null
Default: null
Array of Goals (any) or Goals (null) (Goals)
Default: null
Array of objects (Invoke Skills)

Responses

Request samples

Content type
application/json
{
  • "client_context": null,
  • "message": null,
  • "client_tools": null,
  • "analysis_scope": null,
  • "goals": null,
  • "invoke_skills": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null
}

get_tool_details_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
thread_id
required
string
tool_use_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

search_threads

Search agent threads the caller is allowed to read.

The repo enforces a filter whitelist (thread_id, title, created, created_by, status, visibility, created_from_agent_id, subject_id) and a sort whitelist (created). status accepts the lowercase AgentThreadStatus values (not_started, user_turn, roboto_turn, client_tool_turn, goals_failed); visibility accepts the lowercase ThreadVisibility values (private, org).

Two structural authz gates are bound from caller identity and AND-ed onto every query — both are unreachable from the request body:

  • org_id pins the result set to the caller's org.
  • visibility = 'org' OR created_by = caller_user_id hides PRIVATE threads created by other users; the caller sees every ORG-visible thread plus their own private rows. Admins (identity.is_roboto_admin) bypass this gate so the admin thread explorer continues to see every thread in an org — mirroring the per-row check in get_thread_by_id_with_access_check.

Common UI compositions: the dataset-detail "Agent Threads" tab pins subject_id == <dataset_id> as a scope filter; the agent detail page's "threads launched from this agent" list passes created_from_agent_id == <id>.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

collections

Create, read, and modify entities within Roboto's 'collections' domain

get_collection_access

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
collection_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

edit_collection_access

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
collection_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Array of objects (Add)
Array of objects (Remove)

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_collection

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Description (string) or Description (null) (Description)
Default: null
Name (string) or Name (null) (Name)
Default: null
resource_type
string (CollectionResourceType)
Default: "file"
Enum: "dataset" "event" "file" "session"

Type of resource added to a collection

Array of Resources (objects) or Resources (null) (Resources)
Default: null
Array of Tags (strings) or Tags (null) (Tags)
Default: null
Custom Fields (object) or Custom Fields (null) (Custom Fields)
Default: null

Responses

Request samples

Content type
application/json
{
  • "description": null,
  • "name": null,
  • "resource_type": "dataset",
  • "resources": null,
  • "tags": null,
  • "custom_fields": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_collection

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
collection_id
required
string
query Parameters
string or null
content_mode
string
Enum: "summary_only" "references" "full"

Desired content mode for representing a collection

header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_collection

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
collection_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Array of Add Resources (objects) or Add Resources (null) (Add Resources)
Array of Add Tags (strings) or Add Tags (null) (Add Tags)
Description (string) or Description (null) or Description (null) (Description)
Name (string) or Name (null) or Name (null) (Name)
Array of Remove Resources (objects) or Remove Resources (null) (Remove Resources)
Array of Remove Tags (strings) or Remove Tags (null) (Remove Tags)
CustomFieldChangeset (object) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "add_resources": [
    ],
  • "add_tags": [
    ],
  • "description": "string",
  • "name": "string",
  • "remove_resources": [
    ],
  • "remove_tags": [
    ],
  • "custom_fields_changeset": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_collection

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
collection_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_collection_changes

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
collection_id
required
string
query Parameters
string or null
string or null
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

search_collections

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
content_mode
string
Enum: "summary_only" "references" "full"

Desired content mode for representing a collection

header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_collection_tags_for_org

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

comments

Create, read, and modify entities within Roboto's 'comments' domain

create_comment

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
entity_type
required
string (CommentEntityType)
Enum: "action" "collection" "dataset" "file" "invocation" "trigger"

Enumeration of Roboto platform entities that support comments.

This enum defines the types of resources in the Roboto platform that can have comments attached to them. Each value corresponds to a specific domain entity type.

entity_id
required
string (Entity Id)
comment_text
required
string (Comment Text)

Responses

Request samples

Content type
application/json
{
  • "entity_type": "action",
  • "entity_id": "string",
  • "comment_text": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_comment_by_id

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
comment_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_comment

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
comment_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
comment_text
required
string (Comment Text)

Responses

Request samples

Content type
application/json
{
  • "comment_text": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_comment

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
comment_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_comments_for_entity

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
entity_type
required
string
entity_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_recent_comments

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_comments_for_entity_type

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
entity_type
required
string
Enum: "action" "collection" "dataset" "file" "invocation" "trigger"

Enumeration of Roboto platform entities that support comments.

This enum defines the types of resources in the Roboto platform that can have comments attached to them. Each value corresponds to a specific domain entity type.

query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_comments_for_user

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
user_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

config

Create, read, and modify entities within Roboto's 'config' domain

get_org_config

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
org_id
required
string
key
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_org_config

Set an org config value, replacing any existing one; admin_only keys need an admin of that org.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
org_id
required
string
key
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
value
required
any (Value)

Responses

Request samples

Content type
application/json
{
  • "value": null
}

Response samples

Content type
application/json
{
  • "data": null
}

get_user_config

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
key
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_user_config

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
key
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
value
required
any (Value)

Responses

Request samples

Content type
application/json
{
  • "value": null
}

Response samples

Content type
application/json
{
  • "data": null
}

update_user_org_config

Update user config with org-specific context.

This endpoint handles org-scoped user configuration updates. Currently supports:

  • dataset_search_table_preferences: Merges partial table preferences with existing config
  • file_search_table_preferences: Merges partial table preferences with existing config
  • topic_search_table_preferences: Merges partial table preferences with existing config
  • message_path_search_table_preferences: Merges partial table preferences with existing config
  • event_search_table_preferences: Merges partial table preferences with existing config
  • session_search_table_preferences: Merges partial table preferences with existing config

Args: org_id: Organization ID to scope the update key: Config key (URL-encoded) request: Request body containing partial table preferences

Returns: GetConfigResponse with the updated/merged config value

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
org_id
required
string
key
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Preferences)

Responses

Request samples

Content type
application/json
{
  • "preferences": { }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

datasets

Create, read, and modify entities within Roboto's 'datasets' domain

create_dataset

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope datasets.create
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Description (string) or Description (null) (Description)
Default: null

An optional human-readable description for this dataset.

Device Id (string) or Device Id (null) (Device Id)
Default: null

The ID of the device which created this dataset, if applicable.

Name (string) or Name (null) (Name)
Default: null

A short name for this dataset. Must be under 120 characters or less.

object (Metadata)

Initial key-value pairs to associate with this dataset for discovery and search, e.g. { 'softwareVersion': '3.1.4' }

tags
Array of strings (Tags)

Initial tags to associate with this dataset for discovery and search, e.g. ['sunny', 'campaign5']

Custom Fields (object) or Custom Fields (null) (Custom Fields)
Default: null

Initial values for custom fields defined on Datasets in the caller's org, e.g. { 'drone_id': 'DJI-X', 'flight_count': 12 }. Each name must match a Ready custom-field definition for the org's Dataset entity type; values are typed against the field's declared type.

Responses

Request samples

Content type
application/json
{
  • "description": null,
  • "device_id": null,
  • "name": null,
  • "metadata": { },
  • "tags": [
    ],
  • "custom_fields": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_dataset

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_dataset

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
MetadataChangeset (object) or Metadata Changeset (null) (Metadata Changeset)
Description (string) or Description (null) or Description (null) (Description)
Device Id (string) or Device Id (null) or Device Id (null) (Device Id)
Name (string) or Name (null) or Name (null) (Name)
CustomFieldChangeset (object) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "metadata_changeset": {
    },
  • "description": "string",
  • "device_id": "string",
  • "name": "string",
  • "custom_fields_changeset": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_dataset

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_dataset_access

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

edit_dataset_access

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Array of objects (Add)
Array of objects (Remove)

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_directory

Access control

  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
error_if_exists
boolean (Error If Exists)
Default: false
Parent Path (string) or Parent Path (null) (Parent Path)
Default: null
Origination (string) or Origination (null) (Origination)
Default: null
create_intermediate_dirs
boolean (Create Intermediate Dirs)
Default: false

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "error_if_exists": false,
  • "parent_path": null,
  • "origination": null,
  • "create_intermediate_dirs": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

rename_directory

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
new_path
required
string (New Path)
old_path
required
string (Old Path)

Responses

Request samples

Content type
application/json
{
  • "new_path": "string",
  • "old_path": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_events

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_files

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
One of
Array
string

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_directories

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
directory_paths
required
Array of strings (Directory Paths)

Responses

Request samples

Content type
application/json
{
  • "directory_paths": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_directory_child_count

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
directory_path
required
string
show_hidden_files
boolean
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": 0
}

get_directory_contents

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
directory_path
required
string
page_size
number
boolean or null
string or null
string or null
string or null
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

get_directory_file_extensions

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
directory_path
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

move_nodes

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
Array of objects (Operations)

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

query_dataset_files

Execute a query against files within a specific dataset.

Consistency: Eventually Consistent (for API version >= 2026-03-13)

  • Clients using API version < 2026-03-13: Strongly consistent reads
  • Clients using API version >= 2026-03-13: Eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. Results may not immediately reflect very recent writes. If you've just created or updated files and don't see them in the results, retry after a brief delay.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Page Token (string) or Page Token (null) (Page Token)
Default: null
Array of Include Patterns (strings) or Include Patterns (null) (Include Patterns)
Default: null
Array of Exclude Patterns (strings) or Exclude Patterns (null) (Exclude Patterns)
Default: null
Limit (integer) or Limit (null) (Limit)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
Sort Direction (string) or Sort Direction (null) (Sort Direction)
Default: null

Responses

Request samples

Content type
application/json
{
  • "page_token": null,
  • "include_patterns": null,
  • "exclude_patterns": null,
  • "limit": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

batch_cancel_active_invocations_for_dataset

Access control

  • requires_resource_owner_or_admin
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_active_invocation_count

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": 0
}

get_terminal_invocation_count

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": 0
}

list_dataset_sessions

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_dataset_summary

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

generate_dataset_summary

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
One of
Common Knowledge (string) or Common Knowledge (null) (Common Knowledge)
Default: null
User Prompt Guidelines (string) or User Prompt Guidelines (null) (User Prompt Guidelines)
Default: null

Responses

Request samples

Content type
application/json
Example
{
  • "common_knowledge": null,
  • "user_prompt_guidelines": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_dataset_summary

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
summary
required
string (Summary)

Responses

Request samples

Content type
application/json
{
  • "summary": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_topics

List topics in a dataset.

Consistency: Eventually Consistent (for API version >= 2026-03-13)

  • Clients using API version < 2026-03-13: Strongly consistent reads
  • Clients using API version >= 2026-03-13: Eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. Results may not immediately reflect very recent writes. If you've just created or updated topics and don't see them in the results, retry after a brief delay.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_dataset_topic_time_bounds

Get the earliest start and latest end across every topic in a dataset.

Consistency: Eventually Consistent, on the same terms as GET /<dataset_id>/topics, whose topic set this aggregates.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_dataset_trigger_evaluations_count

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": 0
}

create_dataset_if_not_exists

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope datasets.create
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
match_roboql_query
required
string (Match Roboql Query)
required
object (CreateDatasetRequest)

Request payload for creating a new dataset.

Used to specify the initial properties of a dataset during creation, including optional metadata, tags, name, and description.

Responses

Request samples

Content type
application/json
{
  • "match_roboql_query": "string",
  • "create_request": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_credentials

Access control

  • Restricted tokens need the API scope api.everything_else
  • Restricted tokens also need the API scope files.import or files.upload when mode is ReadWrite
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
mode
string
Enum: "ReadOnly" "ReadWrite"

Enum for permission levels of a Roboto resource. It is a best practice to only request/use the minimum permissions required for a given operation.

For example:

  • When listing files associated with a dataset or pulling a container image hosted in Roboto's registry, use ReadOnly permissions.
  • When adding files to a dataset or pushing a container image to Roboto's registry, use ReadWrite permissions.
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_dataset_metadata_keys_for_org

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

query_datasets

Execute a query against datasets.

Consistency: Eventually Consistent (for API version >= 2026-03-13)

  • Clients using API version < 2026-03-13: Strongly consistent reads
  • Clients using API version >= 2026-03-13: Eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. Results may not immediately reflect very recent writes. If you've just created or updated datasets and don't see them in the results, retry after a brief delay.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_dataset_tags_for_org

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
limit
number
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

begin_single_file_upload_legacy

Access control

  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Origination (string) or Origination (null) (Origination)
Default: null

Additional information about what uploaded the file, e.g. roboto client v1.0.0.

file_path
required
string (File Path)

The destination path to upload the file to in the dataset, e.g. recording.bagor path/to/metadata.json.

file_size
required
integer (File Size)

The size of the file in bytes.

Responses

Request samples

Content type
application/json
{
  • "origination": null,
  • "file_path": "string",
  • "file_size": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

complete_single_file_upload_legacy

Access control

  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
path Parameters
dataset_id
required
string
upload_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": null
}

devices

Create, read, and modify entities within Roboto's 'devices' domain

create_device

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
device_id
required
string (Device Id)
Org Id (string) or Org Id (null) (Org Id)
Default: null
object (Metadata)

Initial key-value pairs to associate with this device for discovery and search, e.g. { 'model': 'mk2', 'serial_number': 'SN001234' }

tags
Array of strings (Tags)

Initial tags to associate with this device for discovery and search, e.g. ['production', 'warehouse-a']

Custom Fields (object) or Custom Fields (null) (Custom Fields)
Default: null

Responses

Request samples

Content type
application/json
{
  • "device_id": "string",
  • "org_id": null,
  • "metadata": { },
  • "tags": [
    ],
  • "custom_fields": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_device_by_id

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
device_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_device_by_id

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
device_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
MetadataChangeset (object) or null
Default: null
CustomFieldChangeset (object) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "metadata_changeset": null,
  • "custom_fields_changeset": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_device_by_id

Delete a device and its files, or with keep_files move its files to the org root.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
device_id
required
string
query Parameters
keep_files
boolean
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

list_device_sessions

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
device_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_device_sessions

Create many sessions on this device, each with its files, topics, and schemas, in one call.

Answers 200 once the batch has been processed, even when the platform refused some of its declarations: the response carries one element per declared session, in request order, holding either the session that declaration created or the error that refused it. Every declaration's refusal is decided before anything is written, and the others are written together in one transaction, so a failure the platform did not anticipate, such as the request's deadline, writes none of them. A malformed batch answers 400. A device not registered in this org answers 404, and so does a file an entry declares, or a file a listed representation names, that is not an Available file of the org. All three are settled before the first declaration is written, so the request creates no session. When a session a declaration reuses is deleted before the request commits, the request answers 404 and writes nothing.

Each anchor_ns in the body is read as roboto.time.to_epoch_nanoseconds reads a time: an integer is nanoseconds since the Unix epoch, a float or numeric string is seconds, and an ISO 8601 string is that instant. An anchor at or before the epoch makes the batch malformed.

Declaring topics on a file or anchoring it writes to that file and so requires edit access to it; an anchor stated on a session applies to every file that session names. Naming a file in a listed representation writes nothing to that file and takes the access that declaring topics on it does, because a read of the topic opens that file. Stating is_default_for_reads on a timeline source, true or false, additionally requires topic edit access in the org: which source a schema's reads fall back to is a property of the org's topics, not of any one file. Each denial answers 401 before any session is prepared.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
device_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
Array of objects (Sessions) [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "sessions": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_tokens_for_device

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
device_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

create_token_for_device

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
device_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Array of Api Scopes (strings) or Api Scopes (null) (Api Scopes)
Default: null

Optional set of API scopes to grant this token.

Description (string) or Description (null) (Description)
Default: null

An optional longer description for this token.

expiry_days
required
integer (Expiry Days)

Number of days until the token expires

name
required
string (Name)

A human-readable name for this token.

Responses

Request samples

Content type
application/json
{
  • "api_scopes": null,
  • "description": null,
  • "expiry_days": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

infer_devices

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
file_ids
required
Array of strings (File Ids)

Responses

Request samples

Content type
application/json
{
  • "file_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_devices_by_org

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
org_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

events

Create, read, and modify entities within Roboto's 'events' domain

create_event

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Array of objects (Associations)
Description (string) or Description (null) (Description)
Default: null
end_time
required
integer (End Time)
object (Metadata)
name
required
string (Name)
start_time
required
integer (Start Time)
tags
Array of strings (Tags)
EventDisplayOptions (object) or null
Default: null
Custom Fields (object) or Custom Fields (null) (Custom Fields)
Default: null

Responses

Request samples

Content type
application/json
{
  • "associations": [
    ],
  • "description": null,
  • "end_time": 0,
  • "metadata": { },
  • "name": "string",
  • "start_time": 0,
  • "tags": [
    ],
  • "display_options": null,
  • "custom_fields": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_events

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
event_ids
required
Array of strings (Event Ids)

Responses

Request samples

Content type
application/json
{
  • "event_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_event_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
event_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_event

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
event_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Description (string) or Description (null) or Description (null) (Description)
MetadataChangeset (object) or Metadata Changeset (null) (Metadata Changeset)
Name (string) or Name (null) (Name)
Start Time (integer) or Start Time (null) (Start Time)
End Time (integer) or End Time (null) (End Time)
EventDisplayOptionsChangeset (object) or Display Options Changeset (null) (Display Options Changeset)
CustomFieldChangeset (object) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "metadata_changeset": {
    },
  • "name": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "display_options_changeset": {
    },
  • "custom_fields_changeset": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_event

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
event_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_event_metadata_keys_for_org

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

query_events_for_associations

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
Array of objects (Associations)
Page Token (string) or Page Token (null) (Page Token)
Default: null

Responses

Request samples

Content type
application/json
{
  • "associations": [
    ],
  • "page_token": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_event_tags_for_org

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
limit
number
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

feature-flags

Create, read, and modify entities within Roboto's 'feature-flags' domain

get_all_feature_flags

List every non-deleted feature flag (admin-only).

Triggered when an operator opens the admin feature-flags panel. Soft-deleted flags are excluded; see get_all_deleted_feature_flags for those.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

create_feature_flag

Define a new feature flag.

Triggered when a Roboto operator registers a new flag (admin-only). The caller's identity is recorded as the flag's creator and initial modifier.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
Description (string) or Description (null) (Description)
Default: null
rollout_status
string (RolloutStatus)
Default: "NoUsers"
Enum: "NoUsers" "Partial" "AllUsers"

Determines which users see a feature flag as enabled.

  • NoUsers: the flag is off for everyone, regardless of group membership.
  • Partial: the flag is on only for users who belong to at least one of the groups listed in FeatureFlagRecord.rollout_user_group_ids.
  • AllUsers: the flag is on for everyone; rollout_user_group_ids is ignored.
rollout_user_group_ids
Array of strings (Rollout User Group Ids)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": null,
  • "rollout_status": "NoUsers",
  • "rollout_user_group_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

check_all_feature_flags_legacy

Evaluate every feature flag for the calling user, optionally scoped to identity.caller_org_id.

Deprecated in favour of check_all_feature_flags_by_org, which answers for every org at once. Kept, unchanged, so clients written against this shape keep working — including web-ui bundles already running in browsers, which send no API version header and so cannot be told apart from any other caller.

Raises: RobotoUnauthorizedException: identity.caller_org_id is set and the caller is not a member.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

check_all_feature_flags_by_org

Evaluate every feature flag for the calling user, keyed by org.

The response covers every org the caller is a member of, so a client fetches it once per session and indexes it by whichever org is active. Membership comes from org_users, which has no row for an org a Roboto admin is viewing without having joined. So when identity.caller_org_id names an org the caller can access but the membership lookup did not return, that org is added, resolved as the single-org check resolves it.

Any identity.caller_org_id that reaches this route names an org the caller can access, whether it came from the org header or from the single-org default: identity extraction rejects a request whose caller org resolves to access level NONE with RobotoUnauthorizedException before any route runs (auth.extraction).

Example::

{"og_123": {"my_flag": true}, "og_456": {"my_flag": false}}

A flag rolled out to one org reads as enabled there and disabled elsewhere, which the single-org check endpoint cannot express without one request per org.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

get_all_deleted_feature_flags

List every soft-deleted feature flag (admin-only).

Triggered when an operator opens the "deleted flags" view in the admin panel to choose one to restore. Live (non-deleted) flags are excluded.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_feature_flag

Fetch a single feature flag by its ID (admin-only).

Triggered when an operator drills into a specific flag in the admin panel. Raises if the flag does not exist or has been soft-deleted.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
feature_flag_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_feature_flag

Patch an existing feature flag (admin-only).

Triggered when an operator edits a flag's name, description, rollout status, or replaces its associated user-group set wholesale. Only fields the request explicitly sets are changed; NotSet fields are left alone. When rollout_user_group_ids is provided it fully replaces the existing set (it is not merged with the prior value); for additive/subtractive changes use the /rollout-groups endpoints instead.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
feature_flag_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Name (string) or Name (null) (Name)
Description (string) or Description (null) or Description (null) (Description)
RolloutStatus (string) or Rollout Status (null) (Rollout Status)
Array of Rollout User Group Ids (strings) or Rollout User Group Ids (null) (Rollout User Group Ids)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "rollout_status": "NoUsers",
  • "rollout_user_group_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_feature_flag

Soft-delete a feature flag (admin-only).

Triggered when an operator removes a flag from the admin panel. The row is marked deleted rather than physically removed, so it can be brought back via restore_feature_flag. After this call the flag stops appearing in get_all_feature_flags and check results.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
feature_flag_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

restore_feature_flag

Undo a soft-delete, returning the flag to the live set (admin-only).

Triggered when an operator restores a previously deleted flag from the admin panel. The flag's prior rollout status and user-group associations are preserved. The caller is recorded as the modifier.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
feature_flag_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_rollout_groups

Return the user-group IDs currently associated with a flag (admin-only).

Triggered when an operator inspects which groups a flag is scoped to. The list reflects the stored associations regardless of rollout_status; note that the IDs only gate access when rollout_status is Partial.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
feature_flag_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

add_rollout_groups

Associate one or more user groups with a flag's rollout set (admin-only).

Triggered when an operator scopes a flag to additional user groups (e.g. expanding a Partial rollout to a new beta cohort). The provided IDs are unioned with the flag's existing rollout-group set, so re-adding a group that is already associated is a no-op rather than an error. Existing associations are not disturbed. Returns the updated flag record.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
feature_flag_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
user_group_ids
required
Array of strings (User Group Ids)

Responses

Request samples

Content type
application/json
{
  • "user_group_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

remove_rollout_groups

Disassociate one or more user groups from a flag's rollout set (admin-only).

Triggered when an operator narrows a flag's scope by removing groups (e.g. pulling a cohort out of a beta). Removing a group that is not currently associated is a no-op. Returns the updated flag record.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
feature_flag_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
user_group_ids
required
Array of strings (User Group Ids)

Responses

Request samples

Content type
application/json
{
  • "user_group_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

check_feature_flag

Evaluate a single named feature flag for the calling user, optionally scoped to identity.caller_org_id.

An unknown feature_flag_name returns {"enabled": false} rather than 404. This is deliberate: clients reference flags by name in code that may outlive the flag (or land before the flag is created), and the eval path treats a missing definition as "off" so callers do not need to special-case 404. Use the admin GET /feature-flags/id/<id> route when an unknown id should surface as a not-found error instead.

Raises: RobotoUnauthorizedException: identity.caller_org_id is set and the caller is not a member.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
feature_flag_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

files

Create, read, and modify entities within Roboto's 'files' domain

delete_file

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
file_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

rename_file

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
file_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
association_id
required
string (Association Id)
new_path
required
string (New Path)

Responses

Request samples

Content type
application/json
{
  • "association_id": "string",
  • "new_path": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_signed_url

Mint a signed URL for one version of a file's object, the current one by default.

A link stores no object, so it is refused rather than followed; the caller resolves the link and asks for its target at the version the link pins.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
file_id
required
string
query Parameters
string or null
string or null
number or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_all_records_for_association

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
association_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_credentials_for_association

Issue read-only credentials for the files associated with a dataset, an org, or a device.

Writes go through an upload transaction's credentials, so mode must be ReadOnly.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
association_id
required
string
query Parameters
mode
string
Enum: "ReadOnly" "ReadWrite"

Enum for permission levels of a Roboto resource. It is a best practice to only request/use the minimum permissions required for a given operation.

For example:

  • When listing files associated with a dataset or pulling a container image hosted in Roboto's registry, use ReadOnly permissions.
  • When adding files to a dataset or pushing a container image to Roboto's registry, use ReadWrite permissions.
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

list_directories

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
association_id
required
string
query Parameters
string or null
page_size
number
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_directory_for_association

Create a directory among the files associated with a dataset, an org, or a device.

Access control

  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
path Parameters
association_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
error_if_exists
boolean (Error If Exists)
Default: false
Parent Path (string) or Parent Path (null) (Parent Path)
Default: null
Origination (string) or Origination (null) (Origination)
Default: null
create_intermediate_dirs
boolean (Create Intermediate Dirs)
Default: false

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "error_if_exists": false,
  • "parent_path": null,
  • "origination": null,
  • "create_intermediate_dirs": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_directory_contents_for_association

List one directory level of the files associated with a dataset, an org, or a device.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
association_id
required
string
query Parameters
directory_path
required
string
page_size
number
boolean or null
string or null
string or null
string or null
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

rename_directory_for_association

Move or rename a directory among the files associated with a dataset, an org, or a device.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
association_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
new_path
required
string (New Path)
old_path
required
string (Old Path)

Responses

Request samples

Content type
application/json
{
  • "new_path": "string",
  • "old_path": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

query_files_for_association

List the available files associated with a dataset, an org, or a device, one page at a time.

The body is the dataset file query; its fields apply the same way to an org or device.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
association_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Page Token (string) or Page Token (null) (Page Token)
Default: null
Array of Include Patterns (strings) or Include Patterns (null) (Include Patterns)
Default: null
Array of Exclude Patterns (strings) or Exclude Patterns (null) (Exclude Patterns)
Default: null
Limit (integer) or Limit (null) (Limit)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
Sort Direction (string) or Sort Direction (null) (Sort Direction)
Default: null

Responses

Request samples

Content type
application/json
{
  • "page_token": null,
  • "include_patterns": null,
  • "exclude_patterns": null,
  • "limit": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_export_job

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
node_ids
required
Array of strings (Node Ids)

Responses

Request samples

Content type
application/json
{
  • "node_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_export_job

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
export_job_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_file_representations

Replace the representations of the named topics on one already-uploaded file.

Each topic and slice listed ends up with exactly the representations listed; topics and slices not listed keep theirs. The request is all or nothing: nothing is written unless every entry is accepted.

Answers 404 when:

  1. The file is not Available, or a listed representation names a file that is not an Available file of the same org.
  2. An entry names a topic or slice the file does not carry.

Answers 401 when the caller lacks edit access to the file or to a file a listed representation names.

Answers 400 when the request is malformed, or when an entry:

  1. Lists a PARQUET representation for a topic whose data on the file carries a timeline extent on a timeline source of kind message_log_time or message_publish_time.
  2. Lists a representation of a field the topic's schema on the file does not have.
  3. Lists, for a slice, a representation covering what no listed representation readable by row position covers, whether that is the whole topic or one field. A representation is readable by row position when it has no transformations or every one is an encode.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
fs_node_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
Array of objects (Topics) [ 1 .. 500 ] items

Responses

Request samples

Content type
application/json
{
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null
}

set_file_timeline_offsets

Calibrate timelines on a file.

Each entry's unix_epoch_offset_ns is added to stored partition times to place them in Unix-epoch time (session_time_ns = stored_time_ns + unix_epoch_offset_ns). It is a non-negative integer of nanoseconds, or any value roboto.time.to_epoch_nanoseconds reads: a float or numeric string is seconds, and an ISO 8601 string is the instant at which stored time 0 occurred. Selectors narrow which extents an entry touches:

  1. topic_name restricts the entry to one topic on this file.
  2. timeline_source_name or timeline_source_id restricts the entry to a specific timeline source within the selected scope.
  3. An entry with no selectors targets every timeline extent on the file.

When a session declares an explicit time range over this file, that range is stored in anchored time and moves with the data it names: it shifts by the same distance when every partition in the session's slice of the file carries one offset before this write and one after. Partitions that disagree on either side leave no single distance to move by, so the range stays where it is; that is what happens when an entry's selectors reach only part of the slice, or when the slice already sat at more than one offset. Every session holding data this write moved has its aggregate bounds recomputed.

Returns the updated timeline extent records. An extent already carrying the offset an entry assigns is left untouched and omitted, so re-stating an anchor that already holds returns an empty list.

At least one entry is required; an empty request yields a 400. All entries apply in a single transaction. Two conditions yield a 404, each with its own message: the file carries no registered topic data to offset at all, or the entries' selectors together reach no extent on it. An entry that reaches nothing while another entry reaches something is skipped without error. An entry whose offset would move the data it reaches before the Unix epoch or past the largest storable instant (2**63 - 1 ns) yields a 400, and nothing in the request is written. The caller must hold edit access to the file; an unknown file yields a 404.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
fs_node_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
Array of objects (Offsets) non-empty

Responses

Request samples

Content type
application/json
{
  • "offsets": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

declare_file_topics

Register the topic data one already-uploaded file carries, naming no session.

Answers 200 once the request has been processed, even when the platform registered only some of its declarations: the response carries one element per declared topic, in request order, holding either the topic that declaration registered against or the error that refused it. A file that is not Available, or a listed representation naming a file that is not an Available file of the same org, answers 404; a caller without edit access to the file or to a file a listed representation names, 401; and a malformed request, 400. A request stating is_default_for_reads on a timeline source, true or false, also answers 401 unless the caller has topic edit access in the org: which source a schema's reads fall back to is a property of the org's topics, not of any one file. Each of these is settled before the first declaration is prepared, so a refused request registers nothing.

Each declaration's anchor_ns is an integer of nanoseconds since the Unix epoch, or any value roboto.time.to_epoch_nanoseconds reads: a float or numeric string is seconds, and an ISO 8601 string is that instant.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
fs_node_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
Array of objects (Topics) [ 1 .. 500 ] items

Responses

Request samples

Content type
application/json
{
  • "topics": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

import_one

Access control

  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
dataset_id
required
string (Dataset Id)
Description (string) or Description (null) (Description)
Default: null
Device Id (string) or Device Id (null) (Device Id)
Default: null
Array of Tags (strings) or Tags (null) (Tags)
Default: null
Metadata (object) or Metadata (null) (Metadata)
Default: null
relative_path
required
string (Relative Path)
Size (integer) or Size (null) (Size)
Default: null
uri
required
string (Uri)

Responses

Request samples

Content type
application/json
{
  • "dataset_id": "string",
  • "description": null,
  • "device_id": null,
  • "tags": null,
  • "metadata": null,
  • "relative_path": "string",
  • "size": null,
  • "uri": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

import_batch

Access control

  • requires_org
  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
Array of objects (Requests)

Responses

Request samples

Content type
application/json
{
  • "requests": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_file_metadata_keys_for_org

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

query_files

Execute a query against files.

Consistency: Eventually Consistent (for API version >= 2026-03-13)

  • Clients using API version < 2026-03-13: Strongly consistent reads
  • Clients using API version >= 2026-03-13: Eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. Results may not immediately reflect very recent writes. If you've just created or updated files and don't see them in the results, retry after a brief delay.

Access control

  • requires_resource_owner_or_admin
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_file_query_result_count

Get the count of files matching a query.

Consistency: Eventually Consistent (for API version >= 2026-03-13)

  • Clients using API version < 2026-03-13: Strongly consistent reads
  • Clients using API version >= 2026-03-13: Eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. The count may not immediately reflect very recent writes. If you've just created or updated files and don't see them in the count, retry after a brief delay.

Access control

  • requires_resource_owner_or_admin
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": 0
}

get_file_record_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
file_id
required
string
query Parameters
number or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_file_record

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
file_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Description (string) or Description (null) or Description (null) (Description)
Device Id (string) or Device Id (null) or Device Id (null) (Device Id)
MetadataChangeset (object) or Metadata Changeset (null) (Metadata Changeset)
true (boolean) or Ingestion Complete (null) (Ingestion Complete)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "device_id": "string",
  • "metadata_changeset": {
    },
  • "ingestion_complete": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_file_record_by_path

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
url_quoted_file_path
required
string
association_id
required
string
query Parameters
number or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

begin_signed_url_upload

Begin a single file upload with a pre-signed URL.

Creates a file record in pending state and returns a pre-signed URL that can be used to upload the file content directly.

Access control

  • requires_org
  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Association)

Use to declare an association between two Roboto entities.

file_path
required
string (File Path)
file_size
required
integer (File Size)
Origination (string) or Origination (null) (Origination)
Default: null

Responses

Request samples

Content type
application/json
{
  • "association": {
    },
  • "file_path": "string",
  • "file_size": 0,
  • "origination": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_file_tags_for_org

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
limit
number
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

abort_transactions

Access control

  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
transaction_ids
required
Array of strings (Transaction Ids)

Responses

Request samples

Content type
application/json
{
  • "transaction_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null
}

begin_upload

Begin a batch file upload transaction.

Creates file records in pending state and returns upload mappings that specify where each file should be uploaded.

Access control

  • requires_org
  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Association)

Use to declare an association between two Roboto entities.

origination
required
string (Origination)
required
object (Resource Manifest)
Device Id (string) or Device Id (null) (Device Id)
Default: null

Responses

Request samples

Content type
application/json
{
  • "association": {
    },
  • "origination": "string",
  • "resource_manifest": {
    },
  • "device_id": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

complete_upload

Complete a file upload transaction (batch or single).

Marks all pending files as available and schedules trigger evaluation for dataset associations.

Access control

  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
path Parameters
upload_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_upload_credentials

Get temporary credentials for uploading files.

Returns a list of AWS credentials scoped to the upload transaction's storage location(s). Currently returns a single credential for the write bucket, but the list format allows for future multi-bucket upload scenarios.

Access control

  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
path Parameters
upload_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

report_upload_progress

Report progress on a batch upload transaction.

Marks the specified files as having completed upload. Returns one {uri, file_id} pair per reported URI that was marked available.

Access control

  • Restricted tokens need the API scope files.import or files.upload
Authorizations:
http
path Parameters
upload_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
manifest_items
required
Array of strings (Manifest Items)

Responses

Request samples

Content type
application/json
{
  • "manifest_items": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

images

Create, read, and modify entities within Roboto's 'images' domain

get_temporary_container_credentials

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
repository_uri
required
string
permissions
string
Enum: "ReadOnly" "ReadWrite"

Enum for permission levels of a Roboto resource. It is a best practice to only request/use the minimum permissions required for a given operation.

For example:

  • When listing files associated with a dataset or pulling a container image hosted in Roboto's registry, use ReadOnly permissions.
  • When adding files to a dataset or pushing a container image to Roboto's registry, use ReadWrite permissions.
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_container_image

Idempotently delete container image from Roboto's private registry.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
image_uri
required
string (Image Uri)

Responses

Request samples

Content type
application/json
{
  • "image_uri": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

put_container_image_record

Admin only.

Memorialize a container image pushed into Roboto's private registry.

:meta private:

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (ContainerImageRecord)

A wire-transmissible representation of a container image.

Responses

Request samples

Content type
application/json
{
  • "record": {
    }
}

Response samples

Content type
application/json
{
  • "data": null
}

delete_container_image_record

Admin only.

Delete our record of container image that has been removed from Roboto's private registry.

:meta private:

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
image_uri
required
string (Image Uri)

Responses

Request samples

Content type
application/json
{
  • "image_uri": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_container_image_record_deprecated

Retrieve our record of a container image pushed into Roboto's private registry.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
org_id
required
string
image_uri
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_image_records

Return paginated list of container image URIs pushed into Roboto's registry for a given org.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_image_repository

Idempotently create a container image repository in Roboto's private registry. Repositories are namespaced by org.

Returns: The URI of the created repository.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
repository_name
required
string (Repository Name)
immutable_image_tags
required
boolean (Immutable Image Tags)

Responses

Request samples

Content type
application/json
{
  • "repository_name": "string",
  • "immutable_image_tags": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_image_repository

Delete a container image repository in Roboto's private registry.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
repository_name
required
string (Repository Name)
force
boolean (Force)
Default: false

Responses

Request samples

Content type
application/json
{
  • "repository_name": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

repository_contains_image

Does the given Roboto-managed repository contain an image with the given image tag?

Because Roboto's view of its image registry is eventually consistent, it may be useful to poll this endpoint until it returns True or False to know when an image has been pushed to or deleted from Roboto's registry.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
repo_name
required
string
image_tag
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_image_tag_mutability

Update an existing container image repository in Roboto's private registry to either allow or disallow overwriting of image tags.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
repository_name
required
string (Repository Name)
immutable_image_tags
required
boolean (Immutable Image Tags)

Responses

Request samples

Content type
application/json
{
  • "repository_name": "string",
  • "immutable_image_tags": true
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

list_repository_records

Return paginated list of repositories within Roboto's registry for a given org.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

ingestion-rules

Ingestion rules declare which files in an organization are ingestable, and how they are ingested.

list_ingestion_rules

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_ingestion_rule

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
Description (string) or Description (null) (Description)
Default: null
include_patterns
required
Array of strings (Include Patterns)
exclude_patterns
Array of strings (Exclude Patterns)
ActionInvocationSpec (object) or null
Default: null
auto_ingest
boolean (Auto Ingest)
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": null,
  • "include_patterns": [
    ],
  • "exclude_patterns": [
    ],
  • "invocation": null,
  • "auto_ingest": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_ingestion_rule

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
rule_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_ingestion_rule

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
rule_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Name (string) or Name (null) (Name)
Default: null
Description (string) or Description (null) (Description)
Default: null
Array of Include Patterns (strings) or Include Patterns (null) (Include Patterns)
Default: null
Array of Exclude Patterns (strings) or Exclude Patterns (null) (Exclude Patterns)
Default: null
ActionInvocationSpec (object) or null
Default: null
Auto Ingest (boolean) or Auto Ingest (null) (Auto Ingest)
Default: null

Responses

Request samples

Content type
application/json
{
  • "name": null,
  • "description": null,
  • "include_patterns": null,
  • "exclude_patterns": null,
  • "invocation": null,
  • "auto_ingest": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_ingestion_rule

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
rule_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

preview_existing_files

Files the rule matches that no rule's trigger has run on. Only org admins, who can ingest them, get their paths: the files may sit in datasets a member cannot open.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
rule_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

ingest_existing_files

Ingest the files GET /<rule_id>/existing-files counts, in the background.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
rule_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_default_ingestion_rules

The default rules, each saying whether the caller's org already has it.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_default_ingestion_rules

Create any of the defaults for new orgs that the caller's org is missing.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

ingest_files

Ingest existing files now with the rules that match them, as an upload of each would have.

Also how a failed ingestion is run again. Needs edit access to each file; a file the caller may not edit is reported not_found.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
file_ids
required
Array of strings (File Ids) [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "file_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

match_ingestion_rules

Which of the caller's org's rules match each path; the same decision that marks a file ingestable.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
paths
required
Array of strings (Paths) <= 200 items

Responses

Request samples

Content type
application/json
{
  • "paths": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

latest_ingestion_runs

The latest run of a rule's trigger on each file in the caller's org that the caller may view; other files are left out as if they had no run.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
file_ids
required
Array of strings (File Ids) [ 1 .. 200 ] items

Responses

Request samples

Content type
application/json
{
  • "file_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

integrations

Create, read, and modify entities within Roboto's 'integrations' domain

list_roboto_regions

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

list_s3_bucket_integrations

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

check_s3_bucket_health

Access control

  • org_admin_only
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
bucket
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

register_s3_integration

Access control

  • deny_actions
  • deny_devices
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
account_id
required
string (Account Id)
aws_region
required
string (Aws Region)
bucket_name
required
string (Bucket Name)
org_id
required
string (Org Id)
transfer_accelerated
boolean (Transfer Accelerated)
Default: false
readonly
boolean (Readonly)
Default: false

Responses

Request samples

Content type
application/json
{
  • "account_id": "string",
  • "aws_region": "string",
  • "bucket_name": "string",
  • "org_id": "string",
  • "transfer_accelerated": false,
  • "readonly": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

layouts

Create, read, and modify entities within Roboto's 'layouts' domain

query_layouts_for_org

Query layouts visible to the caller within their organization.

By default, returns org-wide layouts and the caller's own personal layouts.

Set include_all=true to retrieve every layout in the organization, including other users' personal layouts. This is intended for org-level administration and auditing. Requires the caller to be an org admin; returns 401 Unauthorized otherwise.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
include_all
boolean
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_layout

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
accessibility
string (LayoutAccessibility)
Default: "user"
Enum: "organization" "user"

Controls layout accessibility between organization-wide or user-only.

Folder (string) or Folder (null) (Folder)
Default: null

Folder to group this layout under; null leaves it at the root.

required
object (Layout Definition)

The layout definition as a JSON object.

name
required
string (Name) <= 120 characters

The name of the layout.

schema_version
required
integer (Schema Version)

The schema version associated with the layout definition.

tags
Array of strings (Tags)

The tags associated with the layout.

Responses

Request samples

Content type
application/json
{
  • "accessibility": "organization",
  • "folder": null,
  • "layout_definition": { },
  • "name": "string",
  • "schema_version": 0,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null
}

get_layout_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
layout_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_layout

Update a layout by ID.

Authorization rules:

  • The layout owner can update all fields (name, definition, accessibility, tags, etc.).
  • An org admin who is not the owner can update all fields except name. Attempting to rename another user's layout returns 401 Unauthorized.
  • Any other caller who is not the owner receives 401 Unauthorized.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
layout_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
LayoutAccessibility (string) or Accessibility (null) (Accessibility)

Controls layout accessibility between organization-wide or user-only.

(Folder (Folder (string) or NotSetType (null))) or Folder (null) (Folder)
Default: {}

Folder to move this layout into; null moves it to the root, omit to leave unchanged.

Layout Definition (object) or Layout Definition (null) (Layout Definition)

The layout definition as a JSON object.

Name (string) or Name (null) (Name) <= 120 characters

The name of the layout.

Schema Version (integer) or Schema Version (null) (Schema Version)

The schema version associated with the layout definition.

Array of Tags (strings) or Tags (null) (Tags)

The tags associated with the layout.

Responses

Request samples

Content type
application/json
{
  • "accessibility": "organization",
  • "folder": { },
  • "layout_definition": { },
  • "name": "string",
  • "schema_version": 0,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null
}

delete_layout

Delete a layout by ID.

Authorization rules:

  • The layout's creator can delete it.
  • An org admin who is not the creator can also delete it.
  • Any other caller receives 401 Unauthorized.
  • A layout outside the caller's org returns 404 Not Found.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
layout_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": null
}

get_layout_by_name

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
layout_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

limits

Create, read, and modify entities within Roboto's 'limits' domain

get_ai_credit_usage_for_org

Return the current monthly AI credit usage snapshot for an org.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
org_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_limits_for_org

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
org_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

mcp

Create, read, and modify entities within Roboto's 'mcp' domain

admin_list_mcp_servers

Admin-only: List all registered MCP servers with org_ids populated.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

admin_register_mcp_server

Admin-only: Register an MCP server with optional org scoping.

Supports both DCR and manual registration modes. Set org_ids to scope the server to specific orgs, or leave empty for global visibility.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
registration_mode
string (RegistrationMode)
Default: "manual"
Enum: "dcr" "manual"
server_url
required
string (Server Url)
display_name
required
string (Display Name) <= 32 characters ^[a-zA-Z0-9_-]+$
Oauth Issuer Url (string) or Oauth Issuer Url (null) (Oauth Issuer Url)
Default: null
Authorization Endpoint (string) or Authorization Endpoint (null) (Authorization Endpoint)
Default: null
Token Endpoint (string) or Token Endpoint (null) (Token Endpoint)
Default: null
Client Id (string) or Client Id (null) (Client Id)
Default: null
Client Secret (string) or Client Secret (null) (Client Secret)
Default: null
scopes
Array of strings (Scopes)
Revocation Endpoint (string) or Revocation Endpoint (null) (Revocation Endpoint)
Default: null
org_ids
Array of strings (Org Ids)
object (Extra Auth Params)
Allowed Tools (object) or Allowed Tools (null) (Allowed Tools)
Default: null

Responses

Request samples

Content type
application/json
{
  • "registration_mode": "dcr",
  • "server_url": "string",
  • "display_name": "string",
  • "oauth_issuer_url": null,
  • "authorization_endpoint": null,
  • "token_endpoint": null,
  • "client_id": null,
  • "client_secret": null,
  • "scopes": [
    ],
  • "revocation_endpoint": null,
  • "org_ids": [
    ],
  • "extra_auth_params": {
    },
  • "allowed_tools": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

admin_delete_mcp_server

Admin-only: Delete an MCP server registration. Cascades to all user tokens.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

admin_update_allowed_tools

Admin-only: Set or clear the tool allowlist for an MCP server.

Keys are tool names, values are enabled (true) or blocked (false). Set allowed_tools to null to clear and revert to auto-populate on next discovery.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Allowed Tools (object) or Allowed Tools (null) (Allowed Tools)
Default: null

Responses

Request samples

Content type
application/json
{
  • "allowed_tools": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

admin_copy_allowed_tools

Admin-only: Copy the tool allowlist from another MCP server.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
source_server_id
required
string (Source Server Id)

Responses

Request samples

Content type
application/json
{
  • "source_server_id": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

admin_discover_tools

Admin-only: Discover available tools from an MCP server.

Uses the calling admin's OAuth token for the server in the org given by the org_id query parameter, or that org's org-wide token if the admin has no working connection to the server there.

Returns a list of tool dicts with name, description, inputSchema, and readOnlyHint annotation for each tool.

Raises: RobotoInvalidRequestException: The server rejected every credential tried, naming the last one.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
server_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

admin_update_mcp_server_orgs

Admin-only: Update the org scoping for an MCP server.

Replaces the current org list. Tokens for removed orgs are cascade-deleted. An empty org_ids list makes the server global.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
org_ids
Array of strings (Org Ids)

Responses

Request samples

Content type
application/json
{
  • "org_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

oauth_callback

Exchange an authorization code for tokens.

The server_id and org_id are recovered from the state token stored in the database, so this endpoint doesn't need them in the URL — important because OAuth providers (e.g., GitHub) only redirect with code + state.

Access control

  • requires_org
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
code
required
string (Code)
state
required
string (State)

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "state": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_mcp_org_credentials

List the org-wide MCP server tokens the caller's org has set.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

list_mcp_servers

List MCP servers visible to the caller's org (global + org-scoped).

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

register_mcp_server

Register a new MCP server or return existing if URL matches for the caller's org.

Access control

  • org_admin_only
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
registration_mode
string (RegistrationMode)
Default: "dcr"
Enum: "dcr" "manual"
server_url
required
string (Server Url)
display_name
required
string (Display Name) <= 32 characters ^[a-zA-Z0-9_-]+$
Oauth Issuer Url (string) or Oauth Issuer Url (null) (Oauth Issuer Url)
Default: null
Authorization Endpoint (string) or Authorization Endpoint (null) (Authorization Endpoint)
Default: null
Token Endpoint (string) or Token Endpoint (null) (Token Endpoint)
Default: null
Client Id (string) or Client Id (null) (Client Id)
Default: null
Client Secret (string) or Client Secret (null) (Client Secret)
Default: null
Revocation Endpoint (string) or Revocation Endpoint (null) (Revocation Endpoint)
Default: null
scopes
Array of strings (Scopes)
object (Extra Auth Params)
Allowed Tools (object) or Allowed Tools (null) (Allowed Tools)
Default: null

Responses

Request samples

Content type
application/json
{
  • "registration_mode": "dcr",
  • "server_url": "string",
  • "display_name": "string",
  • "oauth_issuer_url": null,
  • "authorization_endpoint": null,
  • "token_endpoint": null,
  • "client_id": null,
  • "client_secret": null,
  • "revocation_endpoint": null,
  • "scopes": [
    ],
  • "extra_auth_params": {
    },
  • "allowed_tools": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_mcp_server

Get details of a specific MCP server.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_mcp_server

Remove the caller's org from an MCP server, deleting it entirely if this was the only org.

Access control

  • org_admin_only
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_mcp_server_context

Get per-org context for an MCP server.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_mcp_server_context

Set per-org context for an MCP server. This text is injected into the AI system prompt.

Access control

  • org_admin_only
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
context
string (Context) <= 4000 characters
Default: ""

Responses

Request samples

Content type
application/json
{
  • "context": ""
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

start_oauth_flow

Start an OAuth2 authorization flow for the current user and org.

Access control

  • requires_org
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

disconnect_mcp_server

Revoke and delete the current user's token for this server in the current org.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

set_mcp_server_org_credential

Set the org-wide token for an MCP server to the value of one of the caller's org secrets.

Access control

  • org_admin_only
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
secret_name
required
string (Secret Name) non-empty

Responses

Request samples

Content type
application/json
{
  • "secret_name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_mcp_server_org_credential

Remove the org-wide token for an MCP server. The org secret that held it is left in place.

Access control

  • org_admin_only
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
server_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

list_mcp_token_statuses

List token statuses for the current user in their org.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

metrics

Create, read, and modify entities within Roboto's 'metrics' domain

publish_metrics

Record many metric values against one session in a single call.

Answers 201 once the request has been processed, even when the platform refused every value: the response carries one element per submitted metric, in request order, holding either the metric it recorded or the error that refused it. A caller on an API version before 2026-10-05 gets the older shape instead, a succeeded list of stored records beside a failed list of named errors.

Three cases are settled before anything is recorded: a session that does not exist in this org answers 404, a malformed request answers 400, and so does one that omits device_id for a session without exactly one device attached, since there is then no single attached device to record the values against.

A publication that runs out of time answers 504, under RobotoServiceTimeoutException when the invocation's own deadline expired and RobotoOperationTimeoutException when a statement's budget did. Either one rolls the publication back, the definitions it created along with the values.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
session_id
required
string (Session Id)
Device Id (null) or Device Id (string) or Device Id (null) (Device Id)
required
Array of objects (Metrics)

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "device_id": { },
  • "metrics": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

aggregate_metric

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
period
required
string (AggregationPeriod)
Enum: "daily" "weekly" "monthly" "quarterly" "yearly"

Calendar bucket size used when grouping metric observations.

All aggregation start/end times are based on UTC time.

aggregation
required
string (NumericAggregation)
Enum: "sum" "mean" "max" "min" "count"

Aggregation function applied to numeric metric values within each period bucket.

time_filter
string (MetricTimeFilter)
Default: "end_time"
Enum: "start_time" "end_time"
start_time_ns
required
integer (Start Time Ns)
end_time_ns
required
integer (End Time Ns)
Array of Include Device Ids (strings) or Include Device Ids (null) or Include Device Ids (null) (Include Device Ids)
Array of Include Session Ids (strings) or Include Session Ids (null) (Include Session Ids)
Array of Include Invocation Ids (strings) or Include Invocation Ids (null) or Include Invocation Ids (null) (Include Invocation Ids)
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
Group By (string) or Group By (null) (Group By)
Default: null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "period": "daily",
  • "aggregation": "sum",
  • "time_filter": "start_time",
  • "start_time_ns": 0,
  • "end_time_ns": 0,
  • "include_device_ids": [
    ],
  • "include_session_ids": [
    ],
  • "include_invocation_ids": [
    ],
  • "condition": null,
  • "group_by": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_metric_definition

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
Description (string) or Description (null) (Description)
Default: null
Unit (string) or Unit (null) (Unit)
Default: null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": null,
  • "unit": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_metric_definition_by_name

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_metric_definition

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Description (string) or Description (null) or Description (null) (Description)
Unit (null) or Unit (string) or Unit (null) (Unit)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "unit": { }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_metric_definition

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

list_metric_definitions

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
number or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

query_metrics

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
time_filter
string (MetricTimeFilter)
Default: "end_time"
Enum: "start_time" "end_time"
Start Time Ns (integer) or Start Time Ns (null) (Start Time Ns)
Default: null
End Time Ns (integer) or End Time Ns (null) (End Time Ns)
Default: null
max_results
integer (Max Results) ( 0 .. 10000 ]
Default: 10000
Sort By (string) or Sort By (null) (Sort By)
Default: null
descending
boolean (Descending)
Default: false
Array of Include Device Ids (strings) or Include Device Ids (null) or Include Device Ids (null) (Include Device Ids)
Array of Include Session Ids (strings) or Include Session Ids (null) (Include Session Ids)
Array of Include Invocation Ids (strings) or Include Invocation Ids (null) or Include Invocation Ids (null) (Include Invocation Ids)
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
Group By (string) or Group By (null) (Group By)
Default: null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "time_filter": "start_time",
  • "start_time_ns": null,
  • "end_time_ns": null,
  • "max_results": 10000,
  • "sort_by": null,
  • "descending": false,
  • "include_device_ids": [
    ],
  • "include_session_ids": [
    ],
  • "include_invocation_ids": [
    ],
  • "condition": null,
  • "group_by": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_metrics_by_session

Carries no owner-org auth rule, unlike the other routes in this file: the org whose session permissions gate this read is the one that owns the session named in the path.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
query Parameters
number or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

metrics/dashboards

Create, read, and modify entities within Roboto's 'metrics/dashboards' domain

query_dashboards_for_org

Query dashboards visible to the caller within their organization.

By default, returns org-wide dashboards and the caller's own personal dashboards.

Set include_all=true to retrieve every dashboard in the organization, including other users' personal dashboards. This is intended for org-level administration and auditing in CLI/SDK only. Requires the caller to be an org admin; returns 401 Unauthorized otherwise.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
include_all
boolean
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_dashboard

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
accessibility
string (DashboardAccessibility)
Default: "user"
Enum: "organization" "user"

Controls who can view a dashboard.

On create/update requests this is a knob that the server folds into :py:attr:DashboardRecord.owner_principal_id. On :py:class:DashboardRecord it is a derived computed field — always in sync with the owner principal so API consumers never need to parse the principal string themselves.

required
object (Dashboard Definition)
name
required
string (Name) <= 120 characters

Responses

Request samples

Content type
application/json
{
  • "accessibility": "organization",
  • "dashboard_definition": { },
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": null
}

get_dashboard_by_id

Get a dashboard by ID.

Authorization rules (ownership is the sole source of truth — a dashboard is org-wide exactly when owner_principal_id is the org principal):

  • Org-wide dashboards are readable by any member of the owning org.
  • Personal (user-owned) dashboards are readable by their owner or by an org admin of the dashboard's org. Every other caller — a non-owner, non-admin member — receives 404 Not Found. The admin override keeps reads consistent with the list/update/delete powers admins already have.
  • A dashboard outside the caller's orgs returns 404 Not Found.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dashboard_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_dashboard

Update a dashboard by ID.

Authorization rules (ownership is the sole source of truth — a dashboard is org-wide exactly when owner_principal_id is the org principal):

  • Org-wide dashboards are communal: any org member can update all fields, rename included. Retiring one to a personal dashboard (an accessibility request away from organization) is admin-only, since it takes the dashboard away from the whole org.
  • Personal (user-owned) dashboards: the owner and org admins can update all fields, name included. Any other caller receives 401 Unauthorized. An admin rename that lands on a (name, owner) pair the OWNER already holds still returns 409 Conflict via the unique constraint, which keys on the dashboard's owner rather than on who performs the update.

A definition write must carry base_revision (the revision the caller loaded). If the stored definition has advanced since, the write is rejected with 409 RobotoDashboardRevisionConflictException, carrying the server's current record so the caller can resolve without a second round trip. The check runs under the row lock in the persistence layer, not against the authorization fetch below.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dashboard_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
DashboardAccessibility (string) or Accessibility (null) (Accessibility)
Base Revision (integer) or Base Revision (null) (Base Revision)
Dashboard Definition (object) or Dashboard Definition (null) (Dashboard Definition)
Name (string) or Name (null) (Name) <= 120 characters

Responses

Request samples

Content type
application/json
{
  • "accessibility": "organization",
  • "base_revision": 0,
  • "dashboard_definition": { },
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": null
}

delete_dashboard

Delete a dashboard by ID.

Authorization rules:

  • The dashboard owner can delete their dashboard.
  • An org admin who is not the owner can also delete it.
  • Any other caller receives 401 Unauthorized.
  • A dashboard outside the caller's org returns 404 Not Found.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dashboard_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": null
}

notifications

Create, read, and modify entities within Roboto's 'notifications' domain

get_notifications_for_user

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
One of
string
Enum: "unread" "read"

Notification read status enum

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_notification

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
notification_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
notification_id
required
string (Notification Id)
ReadStatus (string) or null
Default: null
Lifecycle Status (object) or Lifecycle Status (null) (Lifecycle Status)
Default: null

Responses

Request samples

Content type
application/json
{
  • "notification_id": "string",
  • "read_status": null,
  • "lifecycle_status": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_notification

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
notification_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

put_notification_records

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
Array of objects (Requests)

Responses

Request samples

Content type
application/json
{
  • "requests": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

orgs

Create, read, and modify entities within Roboto's 'orgs' domain

get_orgs_by_caller

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

update_org_user

Access control

  • org_admin_only
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
org_id
required
string
url_encoded_user_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Array of Add Roles (strings) or Add Roles (null) (Add Roles)
Default: null
Array of Remove Roles (strings) or Remove Roles (null) (Remove Roles)
Default: null

Responses

Request samples

Content type
application/json
{
  • "add_roles": null,
  • "remove_roles": null
}

Response samples

Content type
application/json
{
  • "data": null
}

query

Create, read, and modify entities within Roboto's 'query' domain

convert_natural_language_to_roboql

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
prompt
required
string (Prompt)

Responses

Request samples

Content type
application/json
{
  • "prompt": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_query_record

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
query_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_query_result_count

Get the total number of results for a query.

Consistency: Eventually Consistent (for API version >= 2026-03-13)

  • Clients using API version < 2026-03-13: Strongly consistent reads
  • Clients using API version >= 2026-03-13: Eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. The count may not immediately reflect very recent writes. If you've just created or updated data and don't see it in the count, retry after a brief delay.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
query_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": 0
}

get_query_results

Get paginated results for a query.

Consistency: Eventually Consistent (for API version >= 2026-03-13)

  • Clients using API version < 2026-03-13: Strongly consistent reads
  • Clients using API version >= 2026-03-13: Eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. Results may not immediately reflect very recent writes. If you've just created or updated data and don't see it in the results, retry after a brief delay.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
query_id
required
string
query Parameters
string or null
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_recent_queries

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
required
string or null
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": null
}

submit_roboql_query

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
content_mode
string (QueryContentMode)
Default: "record_with_meta"
Enum: "record_only" "record_with_meta"

The content mode for query results.

required
Query (string) or Query (null) (Query)

The conditions, sorting behavior, and limit of this query.

target
required
string (QueryTarget)
Enum: "collections" "datasets" "devices" "files" "sessions" "topics" "topic_message_paths" "events"

The type of data being requested, e.g. 'Datasets' or 'Topics'.

Responses

Request samples

Content type
application/json
{
  • "content_mode": "record_only",
  • "query": "string",
  • "target": "collections"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

submit_structured_query

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
content_mode
string (QueryContentMode)
Default: "record_with_meta"
Enum: "record_only" "record_with_meta"

The content mode for query results.

required
object (QuerySpecification)

The conditions, sorting behavior, and limit of this query.

target
required
string (QueryTarget)
Enum: "collections" "datasets" "devices" "files" "sessions" "topics" "topic_message_paths" "events"

The type of data being requested, e.g. 'Datasets' or 'Topics'.

Responses

Request samples

Content type
application/json
{
  • "content_mode": "record_only",
  • "query": {
    },
  • "target": "collections"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

submit_term_query

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
content_mode
string (QueryContentMode)
Default: "record_with_meta"
Enum: "record_only" "record_with_meta"

The content mode for query results.

term
string (Term)
Default: ""

A string search term which this query will attempt to match across any appropriate fields.

target
required
string (QueryTarget)
Enum: "collections" "datasets" "devices" "files" "sessions" "topics" "topic_message_paths" "events"

The type of data being requested, e.g. 'Datasets' or 'Topics'.

Responses

Request samples

Content type
application/json
{
  • "content_mode": "record_only",
  • "term": "",
  • "target": "collections"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

secrets

Create, read, and modify entities within Roboto's 'secrets' domain

get_secrets_for_org

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
number or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_secret

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_secret_by_name

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
secret_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_secret_record

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
secret_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_secret_by_name

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
secret_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_secret_creds

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
secret_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

sessions

A Session is an operational time window of a Device, such as a drone flight, a vehicle drive, or a robot arm test run.

list_sessions

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_session

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Description (string) or Description (null) (Description)
Default: null
object (Metadata)
tags
Array of strings (Tags)
Custom Fields (object) or Custom Fields (null) (Custom Fields)
Default: null
CompletionPolicy (object) or Completion Policy (null) or Completion Policy (null) (Completion Policy)
Name (string) or Name (null) (Name)
Default: null
device_ids
Array of strings (Device Ids)

Responses

Request samples

Content type
application/json
{
  • "description": null,
  • "metadata": { },
  • "tags": [
    ],
  • "custom_fields": null,
  • "completion_policy": {
    },
  • "name": null,
  • "device_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_session_if_not_exists

Return the first session matching match_roboql_query, creating create_request when none matches.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
match_roboql_query
required
string (Match Roboql Query)
required
object (CreateSessionRequest)

Request body for POST /v1/sessions.

Creates a new session with zero, one, or many devices attached as subjects.

Responses

Request samples

Content type
application/json
{
  • "match_roboql_query": "string",
  • "create_request": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_session

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_session

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Description (string) or Description (null) or Description (null) (Description)
MetadataChangeset (object) or Metadata Changeset (null) (Metadata Changeset)
Name (string) or Name (null) or Name (null) (Name)
CustomFieldChangeset (object) or null
Default: null
CompletionPolicy (object) or Completion Policy (null) or Completion Policy (null) (Completion Policy)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "metadata_changeset": {
    },
  • "name": "string",
  • "custom_fields_changeset": null,
  • "completion_policy": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_session

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

complete_session

Mark the session complete, after which it is announced ingested whenever its ingestable files are all ingested.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_session_devices

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

attach_to_device

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
device_id
required
string (Device Id)

Responses

Request samples

Content type
application/json
{
  • "device_id": "string"
}

Response samples

Content type
application/json
{
  • "data": null
}

detach_from_device

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
device_id
required
string (Device Id)

Responses

Request samples

Content type
application/json
{
  • "device_id": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

list_session_files

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
query Parameters
string or null
page_size
number
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

add_files

Include files in a session that already exists, each with whatever topic data it declares.

Answers 200 once the request has been processed, even when the platform included only some of the files: the response carries one element per declared file, in request order, holding either that file's membership in the shape GET /v1/sessions/id/<session_id>/files reports it or the error that refused the entry. The request runs in one transaction, and every entry's refusal is settled before anything is written, so a refused entry leaves the others included; a failure the platform did not anticipate, such as the request's deadline, includes none of them. A malformed request answers 400, and a file an entry declares, or a file a listed representation names, that is not an Available file of the session's org answers 404; both are settled before the first entry is written, so the session gains nothing. A session deleted after the request loaded it answers 404, and none of the entries is written.

A client on an API version before 2026-10-05 sends the earlier request shape and receives the session's record. Its request stands or falls whole: when the platform refuses one file it answers with that refusal and includes none of the files, and a file named twice is included over its last entry.

Every anchor_ns in the body is a time after the Unix epoch: an integer of nanoseconds since the epoch, or any time roboto.time.to_epoch_nanoseconds reads, so a float or numeric string is seconds and an ISO 8601 string is that instant.

Declaring topics on a file or anchoring it writes to that file and so requires edit access to it. Naming a file in a listed representation writes nothing to that file and takes the access that declaring topics on it does, because a read of the topic opens that file. Stating is_default_for_reads on a timeline source, true or false, additionally requires topic edit access in the org: which source a schema's reads fall back to is a property of the org's topics, not of any one file. Each denial answers 401 before any entry is prepared.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
Array of objects (Files) [ 1 .. 500 ] items

Responses

Request samples

Content type
application/json
{
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

remove_files

Drop files from a session, in one transaction for the request.

Answers 200 once the request has been processed: the response carries one element per named file, in request order, holding the file's id when the session held it and a not-found error when it did not, and every file the session held is removed. A malformed request answers 400 before any removal runs. A session deleted after the request loaded it answers 404, and a failure the platform did not anticipate, such as the request's deadline, fails the request; either way none of the files is removed.

A client on an API version before 2026-10-05 receives the session's record, and a file the session does not hold is skipped.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
file_ids
required
Array of strings (File Ids) [ 1 .. 500 ] items

Responses

Request samples

Content type
application/json
{
  • "file_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_session_ingestion_status

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

skip_waiting_for

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
file_ids
required
Array of strings (File Ids) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "file_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_session_topics

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_session_topic

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
url_quoted_topic_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_unix_offset

Anchor all of this session's data to wall-clock time.

Every partition inside the slice this session holds of each of its files takes unix_epoch_offset_ns as the wall-clock instant of its stored time 0, and the session's aggregate bounds are recomputed from the moved data. Data that has never been anchored carries an offset of 0, so its stored timestamps already read as nanoseconds since the Unix epoch. Last writer wins: whatever anchor the data carried before is overwritten. The offset is a time after the Unix epoch: an integer of nanoseconds since the epoch, or any time roboto.time.to_epoch_nanoseconds reads, so a float or numeric string is seconds and an ISO 8601 string is that instant. Returning a session to an offset of 0 is the DELETE on this path. Setting the anchor the data already carries changes nothing and succeeds.

The write reaches this session's data and no further. Where several sessions share one file, the slices this session does not hold keep their own anchors; the slices it does hold are shared rather than copied, so every other session over that data reads the anchor written here. The time range the session declares over a file is stored in anchored time and moves with its data, but only when every partition that range covers carries one offset before the write and one after; a range whose data disagrees on where it started has no single distance to move by, and stays where it is.

Returns the session with its recomputed bounds.

Four cases yield a 400: an offset that is not a time strictly between the Unix epoch and 263 ns, a session with no topic data, a session whose data already carries several distinct anchors (anchor one file or one topic at a time instead), and an anchor that would move the session's data, or a time range declared over it, before the Unix epoch or past the largest storable instant (263 - 1 ns). A concurrent writer adding data to the session yields a 409; retry the request.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
unix_epoch_offset_ns
required
integer (Unix Epoch Offset Ns)

Responses

Request samples

Content type
application/json
{
  • "unix_epoch_offset_ns": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

clear_unix_offset

Return this session's data to an offset of 0.

Its stored timestamps are then read as nanoseconds since the Unix epoch with nothing added, and the session's aggregate bounds are recomputed from the moved data. Reaches exactly the data :py:func:set_unix_offset writes, and moves declared time ranges back the same way.

Accepts a session in any anchoring state. Repeating the call, or clearing a session with no anchor or no topic data, changes nothing. A session made of slices anchored at several different instants clears too, each slice moving back by its own anchor.

Returns the session record.

Two cases yield a 400: data with negative timestamps of its own, which an offset of 0 would place before the Unix epoch, and a declared time range whose start would fall before the epoch once it moves back with its data. A concurrent writer adding data to the session yields a 409; retry the request.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_session_ingestion_summaries

Each session's ingestion in counts, for a page of a sessions list. Sessions outside the caller's org are left out.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
session_ids
required
Array of strings (Session Ids) [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "session_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

skills

Create, read, and modify entities within Roboto's 'skills' domain

list_skills

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
limit
number
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_skill

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name) <= 120 characters ^[A-Za-z0-9_-]+$
accessibility
string (SkillAccessibility)
Default: "private"
Enum: "private" "org" "org-editable"

Controls who can see and edit a skill.

description
required
string (Description) <= 500 characters
body
required
string (Body)
tags
Array of strings (Tags)
relevant_topics
Array of strings (Relevant Topics)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "accessibility": "private",
  • "description": "string",
  • "body": "string",
  • "tags": [
    ],
  • "relevant_topics": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_skill_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_skill_metadata

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Name (string) or Name (null) (Name) <= 120 characters
SkillAccessibility (string) or Accessibility (null) (Accessibility)
put_tags
Array of strings (Put Tags)
remove_tags
Array of strings (Remove Tags)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "accessibility": "private",
  • "put_tags": [
    ],
  • "remove_tags": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_skill

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": null
}

subscribe

Subscribe the caller to a skill — records that they care about it and want it in their personal list.

Idempotent. Visibility-gated only: the caller does not have to be the skill's author. ai_version is initialized to NULL (not exposed to AI); use :func:set_subscription to pin a version.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_subscription

Pin (or clear) the caller's AI-available version of a skill.

Upsert semantics: creates the subscription row if missing, otherwise updates ai_version in place. Validates the version exists via the FK.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Ai Version (integer) or Ai Version (null) (Ai Version)
Default: null

Responses

Request samples

Content type
application/json
{
  • "ai_version": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

unsubscribe

Remove the caller's subscription row for a skill. No-op if none exists.

Even authors may unsubscribe from their own skills; authorship is unchanged.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": null
}

get_skill_summary

One skill's summary: the record, its latest version, and the caller's subscription.

The single-skill counterpart of :func:list_skills, for clients that already know the skill id — the web UI's skill detail page reaches it directly from a share link and needs the subscription row to decide whether the reader may edit an org-editable skill. Same visibility gate, and therefore the same 404-not-403 behavior, as :func:get_skill_by_id.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_versions

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

create_version

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
description
required
string (Description) <= 500 characters
body
required
string (Body)
relevant_topics
Array of strings (Relevant Topics)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "body": "string",
  • "relevant_topics": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_version

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
version
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_skill_version

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
version
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Description (string) or Description (null) (Description) <= 500 characters
Body (string) or Body (null) (Body)
Array of Relevant Topics (strings) or Relevant Topics (null) (Relevant Topics)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "body": "string",
  • "relevant_topics": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_skill_version

Delete a single version. Cascades into a full skill delete if it was the last version.

The parent-skill cascade is intentional: an empty skill row would be structurally invalid (no live version to surface, no manual-invocation target) and the UI would have to render a confusing "Empty" state. Authors who want to delete the whole skill can also call DELETE /v1/skills/id/... directly.

Deleting a version is a content edit, so a subscribed editor of an org-editable skill may do it — except when it is the last remaining version, since that cascades into a whole-skill delete (author-only). allow_skill_cascade carries that distinction down to the repo so the last-version check is atomic with the delete.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_id
required
string
version
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": null
}

get_skill_by_name

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
skill_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

list_known_tags

Distinct tags found on skills the caller can see in this org.

Filtered by the same visibility predicate as :func:list_skills — private skills owned by other users (and their tags) are not returned.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

tokens

Create, read, and modify entities within Roboto's 'tokens' domain

list_tokens

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

create_token

Access control

  • deny_actions
  • deny_devices
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Array of Api Scopes (strings) or Api Scopes (null) (Api Scopes)
Default: null

Optional set of API scopes to grant this token.

Description (string) or Description (null) (Description)
Default: null

An optional longer description for this token.

expiry_days
required
integer (Expiry Days)

Number of days until the token expires

name
required
string (Name)

A human-readable name for this token.

Responses

Request samples

Content type
application/json
{
  • "api_scopes": null,
  • "description": null,
  • "expiry_days": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

deprecated_get_token_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
token_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

deprecated_delete_token_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
token_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_token

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
token_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_token

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
token_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

disable_token

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
token_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

enable_token

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
token_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

topics

Create, read, and modify entities within Roboto's 'topics' domain

create_topic

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Association)

Use to declare an association between two Roboto entities.

topic_name
required
string (Topic Name)
End Time (integer) or End Time (null) (End Time)
Default: null
Message Count (integer) or Message Count (null) (Message Count)
Default: null
Metadata (object) or Metadata (null) (Metadata)
Default: null
Schema Checksum (string) or Schema Checksum (null) (Schema Checksum)
Default: null
Schema Name (string) or Schema Name (null) (Schema Name)
Default: null
Start Time (integer) or Start Time (null) (Start Time)
Default: null
Array of Message Paths (objects) or Message Paths (null) (Message Paths)
Default: null

Responses

Request samples

Content type
application/json
{
  • "association": {
    },
  • "topic_name": "string",
  • "end_time": null,
  • "message_count": null,
  • "metadata": null,
  • "schema_checksum": null,
  • "schema_name": null,
  • "start_time": null,
  • "message_paths": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_topics_by_association

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
encoded_association
required
string
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_topic_by_name_and_association

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
encoded_association
required
string
url_quoted_topic_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_topic_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
encoded_association
required
string
url_quoted_topic_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

add_topic_message_path_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
encoded_association
required
string
url_quoted_topic_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
message_path
required
string (Message Path)
data_type
required
string (Data Type)
canonical_data_type
required
string (CanonicalDataType)
Enum: "array" "boolean" "byte" "categorical" "image" "number" "number_array" "object" "string" "timestamp" "unknown" "latdegfloat" "londegfloat" "latdegint" "londegint"

Normalized data types used across different robotics frameworks.

Well-known and simplified data types that provide a common vocabulary for describing message path data types across different frameworks and technologies. These canonical types are primarily used for UI rendering decisions and cross-platform compatibility.

The canonical types abstract away framework-specific details while preserving the essential characteristics needed for data processing and visualization.

References: - ROS 1 field types: http://wiki.ros.org/msg - ROS 2 field types: https://docs.ros.org/en/iron/Concepts/Basic/About-Interfaces.html#field-types - uORB: https://docs.px4.io/main/en/middleware/uorb.html#adding-a-new-topic

Example mappings: - float32 -> CanonicalDataType.Number - uint8[] -> CanonicalDataType.Array - sensor_msgs/Image -> CanonicalDataType.Image - geometry_msgs/Pose -> CanonicalDataType.Object - std_msgs/Header -> CanonicalDataType.Object - string -> CanonicalDataType.String - char -> CanonicalDataType.String - bool -> CanonicalDataType.Boolean - byte -> CanonicalDataType.Byte

object (Metadata)

Initial key-value pairs to associate with this topic message path for discovery and search, e.g. { 'min': 0.71, 'max': 1.77, 'classification': 'my-custom-classification-tag' }

path_in_schema
required
Array of strings (Path In Schema)

List of path components representing the field's location in the source data schema. For nested fields like 'position.x', this would be ['position', 'x'].

Responses

Request samples

Content type
application/json
{
  • "message_path": "string",
  • "data_type": "string",
  • "canonical_data_type": "array",
  • "metadata": { },
  • "path_in_schema": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_topic_message_path_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
encoded_association
required
string
url_quoted_topic_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
message_path
required
string (Message Path)
TaglessMetadataChangeset (object) or Metadata Changeset (null) (Metadata Changeset)
Data Type (string) or Data Type (null) (Data Type)
CanonicalDataType (string) or Canonical Data Type (null) (Canonical Data Type)
Array of Path In Schema (strings) or Path In Schema (null) (Path In Schema)

Responses

Request samples

Content type
application/json
{
  • "message_path": "string",
  • "metadata_changeset": {
    },
  • "data_type": "string",
  • "canonical_data_type": "array",
  • "path_in_schema": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

add_message_path_representation_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
encoded_association
required
string
url_quoted_topic_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Association)

Use to declare an association between two Roboto entities.

storage_format
required
string (RepresentationStorageFormat)
Enum: "mcap" "parquet"

Supported storage formats for topic data representations.

Defines the available formats for storing and accessing topic data within the Roboto platform. Each format has different characteristics and use cases.

version
required
integer (Version)
Format (string) or Format (null) (Format)
Default: null
Array of Transformations (strings) or Transformations (null) (Transformations)
Default: null
message_path_id
required
string (Message Path Id)

Responses

Request samples

Content type
application/json
{
  • "association": {
    },
  • "storage_format": "mcap",
  • "version": 0,
  • "format": null,
  • "transformations": null,
  • "message_path_id": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_default_topic_representation_legacy

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
encoded_association
required
string
url_quoted_topic_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Association)

Use to declare an association between two Roboto entities.

storage_format
required
string (RepresentationStorageFormat)
Enum: "mcap" "parquet"

Supported storage formats for topic data representations.

Defines the available formats for storing and accessing topic data within the Roboto platform. Each format has different characteristics and use cases.

version
required
integer (Version)
Format (string) or Format (null) (Format)
Default: null
Array of Transformations (strings) or Transformations (null) (Transformations)
Default: null

Responses

Request samples

Content type
application/json
{
  • "association": {
    },
  • "storage_format": "mcap",
  • "version": 0,
  • "format": null,
  • "transformations": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_topic_time_bounds_by_association

Get the earliest start and latest end across every topic of a file or dataset.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
encoded_association
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_all_topics_for_association

List every topic version recorded against an association.

Restricted to Roboto platform administrators. Returns at most 100 records; results_remaining is true when more exist.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
association_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_topic_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_topic

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
End Time (integer) or End Time (null) or End Time (null) (End Time)
Message Count (integer) or Message Count (null) (Message Count)
Schema Checksum (string) or Schema Checksum (null) or Schema Checksum (null) (Schema Checksum)
Schema Name (string) or Schema Name (null) or Schema Name (null) (Schema Name)
Start Time (integer) or Start Time (null) or Start Time (null) (Start Time)
MetadataChangeset (object) or Metadata Changeset (null) (Metadata Changeset)
MessagePathChangeset (object) or Message Path Changeset (null) (Message Path Changeset)

Responses

Request samples

Content type
application/json
{
  • "end_time": 0,
  • "message_count": 0,
  • "schema_checksum": "string",
  • "schema_name": "string",
  • "start_time": 0,
  • "metadata_changeset": {
    },
  • "message_path_changeset": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_topic_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

add_topic_message_path_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
message_path
required
string (Message Path)
data_type
required
string (Data Type)
canonical_data_type
required
string (CanonicalDataType)
Enum: "array" "boolean" "byte" "categorical" "image" "number" "number_array" "object" "string" "timestamp" "unknown" "latdegfloat" "londegfloat" "latdegint" "londegint"

Normalized data types used across different robotics frameworks.

Well-known and simplified data types that provide a common vocabulary for describing message path data types across different frameworks and technologies. These canonical types are primarily used for UI rendering decisions and cross-platform compatibility.

The canonical types abstract away framework-specific details while preserving the essential characteristics needed for data processing and visualization.

References: - ROS 1 field types: http://wiki.ros.org/msg - ROS 2 field types: https://docs.ros.org/en/iron/Concepts/Basic/About-Interfaces.html#field-types - uORB: https://docs.px4.io/main/en/middleware/uorb.html#adding-a-new-topic

Example mappings: - float32 -> CanonicalDataType.Number - uint8[] -> CanonicalDataType.Array - sensor_msgs/Image -> CanonicalDataType.Image - geometry_msgs/Pose -> CanonicalDataType.Object - std_msgs/Header -> CanonicalDataType.Object - string -> CanonicalDataType.String - char -> CanonicalDataType.String - bool -> CanonicalDataType.Boolean - byte -> CanonicalDataType.Byte

object (Metadata)

Initial key-value pairs to associate with this topic message path for discovery and search, e.g. { 'min': 0.71, 'max': 1.77, 'classification': 'my-custom-classification-tag' }

path_in_schema
required
Array of strings (Path In Schema)

List of path components representing the field's location in the source data schema. For nested fields like 'position.x', this would be ['position', 'x'].

Responses

Request samples

Content type
application/json
{
  • "message_path": "string",
  • "data_type": "string",
  • "canonical_data_type": "array",
  • "metadata": { },
  • "path_in_schema": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_topic_message_path_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
message_path
required
string (Message Path)
TaglessMetadataChangeset (object) or Metadata Changeset (null) (Metadata Changeset)
Data Type (string) or Data Type (null) (Data Type)
CanonicalDataType (string) or Canonical Data Type (null) (Canonical Data Type)
Array of Path In Schema (strings) or Path In Schema (null) (Path In Schema)

Responses

Request samples

Content type
application/json
{
  • "message_path": "string",
  • "metadata_changeset": {
    },
  • "data_type": "string",
  • "canonical_data_type": "array",
  • "path_in_schema": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

add_message_path_representation_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Association)

Use to declare an association between two Roboto entities.

storage_format
required
string (RepresentationStorageFormat)
Enum: "mcap" "parquet"

Supported storage formats for topic data representations.

Defines the available formats for storing and accessing topic data within the Roboto platform. Each format has different characteristics and use cases.

version
required
integer (Version)
Format (string) or Format (null) (Format)
Default: null
Array of Transformations (strings) or Transformations (null) (Transformations)
Default: null
message_path_id
required
string (Message Path Id)

Responses

Request samples

Content type
application/json
{
  • "association": {
    },
  • "storage_format": "mcap",
  • "version": 0,
  • "format": null,
  • "transformations": null,
  • "message_path_id": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_message_path_representations

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_message_path_representations_by_format

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
storage_format
required
string
Enum: "mcap" "parquet"

Supported storage formats for topic data representations.

Defines the available formats for storing and accessing topic data within the Roboto platform. Each format has different characteristics and use cases.

header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

set_default_topic_representation_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Association)

Use to declare an association between two Roboto entities.

storage_format
required
string (RepresentationStorageFormat)
Enum: "mcap" "parquet"

Supported storage formats for topic data representations.

Defines the available formats for storing and accessing topic data within the Roboto platform. Each format has different characteristics and use cases.

version
required
integer (Version)
Format (string) or Format (null) (Format)
Default: null
Array of Transformations (strings) or Transformations (null) (Transformations)
Default: null

Responses

Request samples

Content type
application/json
{
  • "association": {
    },
  • "storage_format": "mcap",
  • "version": 0,
  • "format": null,
  • "transformations": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_message_path_by_id

Look up a message path by ID.

The caller must hold view access to the file or dataset the message path's topic is recorded against.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
message_path_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_topic_metadata_keys_for_org

Get unique metadata keys from topics across all topics in the organization.

Backward compatibility behavior:

  • Pre-v2026_03_13 clients: Uses strongly consistent reads
  • v2026_03_13+ clients: Uses eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. Results may not immediately reflect very recent writes. If you've just created or updated topic metadata and don't see it in the results, retry after a brief delay.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_field_paths_for_topic

Get the distinct field paths of a single topic, by name, in the organization.

Resolves the topic through the shared-topics/fields model (topic_identity → topic_partition → schema_field) and returns each field's dot-joined path_in_schema (e.g. linear_acceleration.x). The fields shown belong to the referenced topic rather than the org-wide message-path catalog.

Returns paths alone. Callers that need each field's type and unit — to tell a scalar field from an array one without reading a message — should use GET /v1/urdf/bindable_topic_message_paths instead.

Reads only the normalized schema tables. A topic with no normalized rows yet (e.g. one predating the topic-schema tables) returns an empty list.

Consistency: Eventually consistent by default; override with the X-Roboto-Connection-Consistency header.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_all_unique_topic_message_paths_for_org

Get unique message paths across all topics in the organization.

Pass prefix to return only values starting with it, matched against the whole topic_name.message_path string. Results are capped server-side, so for an org with more distinct paths than the cap an unfiltered call returns an arbitrary alphabetical head of the corpus and everything after the cut is unreachable. Autocomplete callers should send what the user has typed rather than filtering a truncated list client-side.

Consistency: Eventually Consistent (for API version >= 2026-03-13)

  • Clients using API version < 2026-03-13: Strongly consistent reads
  • Clients using API version >= 2026-03-13: Eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. Results may not immediately reflect very recent writes. If you've just created message paths and don't see them in the results, retry after a brief delay.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_unique_topic_names_for_org

Get unique topic names across all topics in the organization.

Consistency: Eventually Consistent (for API version >= 2026-03-13)

  • Clients using API version < 2026-03-13: Strongly consistent reads
  • Clients using API version >= 2026-03-13: Eventually consistent reads
  • Override: Send X-Roboto-Connection-Consistency header to explicitly control behavior

This endpoint uses eventual consistency for improved performance and scalability. Results may not immediately reflect very recent writes. If you've just created topics and don't see them in the results, retry after a brief delay.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_topic_identity_by_id

Look up a topic identity by ID.

The caller must hold topic view access in the org that owns the topic.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

resolve_read_plan

Resolve the physical read plan for a topic identity over a time window.

The request body carries the window, the field projection (as field-subtree addresses), an optional per-subtree representation prefer grammar, and optionally names the schema and timeline source to use. A malformed body, or a schema named by both id and checksum, yields a 400.

Authorization is two layers. The caller must first hold topic view access in the org that owns the topic. Within the org, authorization is all-or-nothing over the window, through view access to every in-window partition's backing file: if the caller cannot view any part of the requested window, the whole request fails with a 401 (RobotoUnauthorizedException) rather than returning a plan that silently omits data.

When the body carries a session_id, the read is scoped to the files recorded in that session (so a shared topic name does not pull data from unrelated files org-wide), and the caller must additionally hold session-view access in the org that owns the session; an unknown session yields a 404 and one the caller cannot view yields a 401.

A file_id limits the read to the topic's data in that file, a dataset_id to its data in the dataset's files, and a device_id to its data in the device's files (a file belongs to the device it names, or, when it names none, to the device its dataset names). A named file or dataset must exist (else 404) and the caller must hold view access to it (else 401). A device is not looked up, so an unknown device yields an empty plan. Every restriction the body names narrows the read, and restrictions named together intersect. Data a restriction leaves out does not affect the read: its schemas cause no ambiguity and its files need no access.

With a file, dataset or device named, the body may omit start_time, end_time or both. An omitted bound defaults to the start or end of the topic's data within the body's restrictions, across every timeline source. When the restrictions select no timestamped data for the topic, or the one given bound lies past the far end of that data (a start after the data ends, or an end before it begins), the plan has no partitions and a null window.

A caller pinned to an API version below 2026-10-05 receives on every partition the extent field that SDK releases pinned to those versions require. Such an SDK selects rows by the requested window alone, so a plan is refused for that caller with a 400 (RobotoDeprecatedException) asking them to upgrade when any partition owns a slice of a shared file, or when a session narrows any partition's window below the requested one: reading it on that version would return rows belonging to another session or to another partition packed in the same file.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Start Time (integer) or Start Time (null) (Start Time)
Default: null
End Time (integer) or End Time (null) (End Time)
Default: null
Array of Fields Include (objects) or Fields Include (null) (Fields Include)
Default: null
Array of Fields Exclude (objects) or Fields Exclude (null) (Fields Exclude)
Default: null
RepresentationPreference (object) or null
Default: null
Schema Id (string) or Schema Id (null) (Schema Id)
Default: null
Schema Checksum (string) or Schema Checksum (null) (Schema Checksum)
Default: null
Timeline Source Id (string) or Timeline Source Id (null) (Timeline Source Id)
Default: null
Timeline Source Name (string) or Timeline Source Name (null) (Timeline Source Name)
Default: null
Session Id (string) or Session Id (null) (Session Id)
Default: null
File Id (string) or File Id (null) (File Id)
Default: null
Dataset Id (string) or Dataset Id (null) (Dataset Id)
Default: null
Device Id (string) or Device Id (null) (Device Id)
Default: null

Responses

Request samples

Content type
application/json
{
  • "start_time": null,
  • "end_time": null,
  • "fields_include": null,
  • "fields_exclude": null,
  • "prefer": null,
  • "schema_id": null,
  • "schema_checksum": null,
  • "timeline_source_id": null,
  • "timeline_source_name": null,
  • "session_id": null,
  • "file_id": null,
  • "dataset_id": null,
  • "device_id": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_topic_unix_offset

Anchor the data one session holds for one topic to wall-clock time.

unix_epoch_offset_ns is added to the stored timestamps of every partition of this topic that the session's membership claims admit, so they read as wall-clock time (session_time_ns = stored_time_ns + unix_epoch_offset_ns). This is the write for a session whose data all starts from one time 0 but is stored apart: chunked across several files, or packed into slices of one shared file. All of its partitions move in one transaction, so a failure leaves every one of them at the offset it already had.

The offset is an integer of nanoseconds since the Unix epoch, or any time roboto.time.to_epoch_nanoseconds reads: a float or numeric string is seconds, and an ISO 8601 string is that instant.

The offsets are stored on the partitions' timeline extents, which belong to the files rather than to the session: any other session holding the same data sees the same anchor. A membership's declared time range is stored in anchored time, so it moves with its data, but only when everything the membership claims moved by one distance; a membership whose claim also covers data this write leaves alone (another topic in the same file or slice) keeps its declared range. To move a whole session at once, use the session's own unix-offset endpoint, or declare its anchor_ns at ingest; the file's timeline-offsets endpoint with no selector does the same in one call only when the whole session is one whole file.

Returns the updated timeline extent records.

The caller must hold session-view access in the org that owns the session, and edit access to every file behind the data being written. An unknown session yields a 404, and one the caller cannot view yields a 401. The topic is reached only through the session's partitions, so both an unknown topic and one the session holds no data for yield a 404.

An offset yields a 400 when it cannot be read as a time, when it does not fall after the Unix epoch and below 263 ns, or when it would move the data it reaches, or a time range declared over that data, before the Unix epoch or past the largest storable instant (263 - 1 ns). A concurrent writer adding data to the session yields a 409; retry the request.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
session_id
required
string (Session Id)
unix_epoch_offset_ns
required
integer (Unix Epoch Offset Ns)

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "unix_epoch_offset_ns": 0
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

clear_topic_unix_offset

Return the data one session holds for one topic to an offset of 0.

Its stored timestamps are then read as nanoseconds since the Unix epoch with nothing added. The inverse of :py:func:set_topic_unix_offset in every other respect, including which data it reaches and how declared time ranges follow it back.

Returns the updated timeline extent records.

Clearing yields a 400 when the data has negative timestamps of its own, which offset 0 places before the Unix epoch, or when a declared time range moved back with its data would start before the epoch. A concurrent writer adding data to the session yields a 409; retry the request.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_id
required
string
query Parameters
session_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

list_timeline_extents

List the timeline extents for a topic partition.

A topic partition is one file's contribution to a topic; an extent is the (min_ns, max_ns) range that partition covers under one timeline source. The caller must have view access to the file the partition belongs to.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
topic_part_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_schema_by_id

Look up a topic schema by ID.

The caller must hold topic view access in the org that owns the schema.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
schema_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_schema_fields

List the fields declared by a topic schema.

The caller must hold topic view access in the org that owns the schema.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
schema_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

list_timeline_sources

List every timeline source registered for a schema.

The caller must hold topic view access in the org that owns the schema.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
schema_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

update_timeline_source

Rename a timeline source, or change which source is the schema's default.

Only the fields explicitly set on the request are changed. The caller must hold topic edit access in the org that owns the schema. A source that is not on this schema is refused as not found.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
schema_id
required
string
timeline_source_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Is Default (boolean) or Is Default (null) (Is Default)
Name (string) or Name (null) (Name)

Responses

Request samples

Content type
application/json
{
  • "is_default": true,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_timeline_source

Remove a timeline source from a schema.

Also drops every timeline extent measured against the source and recomputes the timestamp bounds of every session composed from a file those extents covered. Runs synchronously, so this can be slow when the source is widely used. The caller must hold topic edit access in the org that owns the schema, and a source that is not on this schema is refused as not found. An ingest registering new data under the source while this request is being prepared fails the request with a 409; retry it.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
schema_id
required
string
timeline_source_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

triggers

Create, read, and modify entities within Roboto's 'triggers' domain

list_triggers

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_trigger

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name) <= 256 characters [\w\-]+
required
any (Fires On)
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
required
Array of any (Targets)
enabled
boolean (Enabled)
Default: true
Service User Id (string) or Service User Id (null) (Service User Id)
Default: null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "fires_on": {
    },
  • "condition": null,
  • "targets": [
    ],
  • "enabled": true,
  • "service_user_id": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_trigger_by_name

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_trigger

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Fires On (any) or Fires On (null) (Fires On)
Condition (object) or ConditionGroup (object) or Condition (null) or Condition (null) (Condition)
Array of Targets (any) or Targets (null) (Targets)
Enabled (boolean) or Enabled (null) (Enabled)
Service User Id (string) or Service User Id (null) (Service User Id)
Default: null
LegacyInvokeActionPatch (object) or Legacy Target Patch (null) (Legacy Target Patch)
LegacyEventSubscriptionPatch (object) or Legacy Source Patch (null) (Legacy Source Patch)

Responses

Request samples

Content type
application/json
{
  • "fires_on": {
    },
  • "condition": {
    },
  • "targets": [
    ],
  • "enabled": true,
  • "service_user_id": null,
  • "legacy_target_patch": {
    },
  • "legacy_source_patch": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_trigger

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_trigger_evaluations

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_name
required
string
query Parameters
limit
number
string or null
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

query_aggregated_triggers

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_dataset_trigger_dispatches

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
limit
number
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_dataset_trigger_evaluations

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
query Parameters
limit
number
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_dataset_trigger_evaluations_summary

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
dataset_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_event_samples

A realistic, dereferenced sample of every platform event type.

Pure: built from the SDK's sample scenario through the same EventNamespace the evaluator uses, so what it shows is what a condition or target template can reference. Nothing here is org-specific; the route is authenticated but reads no resource.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_trigger_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_trigger_dispatches

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_id
required
string
query Parameters
limit
number
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

dry_run_trigger

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
PlatformEvent (object) or null
Default: null
Dataset Id (string) or Dataset Id (null) (Dataset Id)
Default: null
File Id (string) or File Id (null) (File Id)
Default: null
Invocation Id (string) or Invocation Id (null) (Invocation Id)
Default: null
Event Id (string) or Event Id (null) (Event Id)
Default: null
Scheduled For (string) or Scheduled For (null) (Scheduled For)
Default: null
PlatformEventType (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "event": null,
  • "dataset_id": null,
  • "file_id": null,
  • "invocation_id": null,
  • "event_id": null,
  • "scheduled_for": null,
  • "event_type": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_trigger_evaluations_count

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": 0
}

query_triggers

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Condition (object) or ConditionGroup (object) or Condition (null) (Condition)
Default: null
limit
integer (Limit)
Default: 1000
Max Results (integer) or Max Results (null) (Max Results)
Default: null
After (string) or After (null) (After)
Default: null
Sort By (string) or Sort By (null) (Sort By)
Default: null
SortDirection (string) or null
Default: null

Responses

Request samples

Content type
application/json
{
  • "condition": null,
  • "limit": 1000,
  • "max_results": null,
  • "after": null,
  • "sort_by": null,
  • "sort_direction": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_scheduled_trigger

Retired route: creates a schedule-fired trigger and answers in the old shape.

Access control

  • requires_org
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
action_name
required
string (Action Name) [\w\-]+
Action Owner Id (string) or Action Owner Id (null) (Action Owner Id)
Default: null
ComputeRequirements (object) or null
Default: null
ContainerParameters (object) or null
Default: null
enabled
required
boolean (Enabled)
InvocationInput (object) or null
Default: null
InvocationUploadDestination (object) or null
Default: null
name
required
string (Name) <= 256 characters [\w\-]+
Parameter Values (object) or Parameter Values (null) (Parameter Values)
Default: null
schedule
required
string (Schedule)
Timeout (integer) or Timeout (null) (Timeout)
Default: null

Responses

Request samples

Content type
application/json
{
  • "action_name": "string",
  • "action_owner_id": null,
  • "compute_requirement_overrides": null,
  • "container_parameter_overrides": null,
  • "enabled": true,
  • "invocation_input": null,
  • "invocation_upload_destination": null,
  • "name": "string",
  • "parameter_values": null,
  • "schedule": "string",
  • "timeout": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_scheduled_trigger_by_name

Retired route: reads a schedule-fired trigger by name in the old shape.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_scheduled_trigger_by_id

Retired route: reads a schedule-fired trigger in the old shape.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_scheduled_trigger

Retired route: applies the old partial update to a schedule-fired trigger.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Action Name (string) or Action Name (null) (Action Name)
Action Owner Id (string) or Action Owner Id (null) (Action Owner Id)
ComputeRequirements (object) or Compute Requirement Overrides (null) or Compute Requirement Overrides (null) (Compute Requirement Overrides)
ContainerParameters (object) or Container Parameter Overrides (null) or Container Parameter Overrides (null) (Container Parameter Overrides)
Enabled (boolean) or Enabled (null) (Enabled)
InvocationInput (object) or Invocation Input (null) or Invocation Input (null) (Invocation Input)
InvocationUploadDestination (object) or Invocation Upload Destination (null) or Invocation Upload Destination (null) (Invocation Upload Destination)
Parameter Values (object) or Parameter Values (null) or Parameter Values (null) (Parameter Values)
Schedule (string) or Schedule (null) (Schedule)
Timeout (integer) or Timeout (null) or Timeout (null) (Timeout)

Responses

Request samples

Content type
application/json
{
  • "action_name": "string",
  • "action_owner_id": "string",
  • "compute_requirement_overrides": {
    },
  • "container_parameter_overrides": {
    },
  • "enabled": true,
  • "invocation_input": {
    },
  • "invocation_upload_destination": {
    },
  • "parameter_values": { },
  • "schedule": "string",
  • "timeout": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_scheduled_trigger

Retired route: deletes a schedule-fired trigger. Idempotent.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
trigger_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

urdf

Generate and edit viewable glTF assets from URDF robot descriptions and PLY point clouds.

get_bindable_topic_message_paths

Get the distinct message paths of a single topic, by name, with their types and units.

Resolves the topic the same way as GET /v1/topics/unique/topic_fields, but returns one entry per distinct message path rather than the path alone, carrying the type and unit the topic's schema versions agree on. Lets the joint-binding dialog tell a scalar path from an array one without reading a message, and gives field autocomplete something to show beside each path.

An attribute is populated only when every contributing schema version agrees on it; on disagreement it is null and named in the entry's conflicting_attributes, so a caller can never mistake disagreement for an unset value.

topic_name is a query parameter rather than a path segment because topic names contain slashes (/imu/data).

Reads only the normalized schema tables. A topic with no normalized rows yet (e.g. one predating the topic-schema tables) returns an empty list.

Consistency: Eventually consistent by default; override with the X-Roboto-Connection-Consistency header.

Access control

  • requires_resource_owner
  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

request_visualization_asset

Queue conversion of a URDF file or PLY point cloud into a viewable glTF asset.

Access control

  • Restricted tokens need the API scope api.everything_else and files.import or files.upload
Authorizations:
http
path Parameters
file_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
collision
boolean (Collision)
Default: false
z_up
boolean (Z Up)
Default: false
articulation
boolean (Articulation)
Default: true
packages
string (Packages)
Default: ""
strict
boolean (Strict)
Default: false

Responses

Request samples

Content type
application/json
{
  • "collision": false,
  • "z_up": false,
  • "articulation": true,
  • "packages": "",
  • "strict": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

set_joint_bindings

Queue writing the default joint bindings for a URDF into the glTF asset generated from it.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
file_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
object (Bindings)

Responses

Request samples

Content type
application/json
{
  • "bindings": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

user-groups

Create, read, and modify entities within Roboto's 'user-groups' domain

get_all_user_groups

List every user group in the system.

Triggered when an admin opens the user-groups admin panel, or when the feature-flags admin panel needs the full set of groups so an operator can pick which ones a flag should be associated with. Returns every record unfiltered and unpaginated — the expected cardinality is small (tens).

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

create_user_group

Create a user group (a named, admin-managed set of user ids used to gate features).

Triggered when a Roboto admin submits the "new user group" form. The group's name and initial members come from request; the caller is recorded as the creator. The parent row and the initial membership rows are written in a single transaction, so the group is never observable without its declared starting members. Raises if the requested name is already taken.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name)
members
Array of strings (Members)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_user_group

Look up a single user group by its ug_... id.

Triggered when an admin opens the detail view for a specific group, or when another service has a stored id and needs to resolve the current name and membership. Raises RobotoNotFoundException if no such group exists.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
user_group_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_user_group

Rename a user group and/or replace its full membership list.

Triggered when an admin saves edits in the user-group detail panel. request.members is a wholesale replacement of the membership set — to incrementally add or remove members without rewriting the whole list, use the dedicated /members endpoints below instead. The parent-row update and the membership rewrite happen inside one transaction so readers never see a half-applied change.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
user_group_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Name (string) or Name (null) (Name)
Array of Members (strings) or Members (null) (Members)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_user_group

Permanently delete a user group and its membership rows.

Triggered when an admin clicks "delete" on a group. Refuses (raising RobotoConflictException) if any feature flag still references this group — the operator must first detach the group from every flag that uses it, otherwise the flag's audience would silently lose its definition. Returns 204 No Content on success.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
user_group_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

add_user_group_members

Add user ids to an existing group's membership without disturbing current members.

Triggered when an admin uses the "add members" control on the group detail panel. request.members are inserted alongside the current membership; user ids that are already members are no-ops. Returns the updated record.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
user_group_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
members
required
Array of strings (Members)

Responses

Request samples

Content type
application/json
{
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

remove_user_group_members

Remove user ids from a group's membership, leaving the group itself in place.

Triggered when an admin uses the "remove members" control on the group detail panel. User ids in request.members that are not currently members are no-ops; the group is preserved even if the call empties it. Returns the updated record.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
user_group_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
members
required
Array of strings (Members)

Responses

Request samples

Content type
application/json
{
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_user_group_by_name

Look up a single user group by its unique display name.

Triggered when an operator (or the feature-flag admin flow) has a group name in hand — typically the value typed into a "associate user group with this flag" picker — and needs to resolve it to the current record before storing the association. Raises RobotoNotFoundException if no group with that name exists.

Access control

  • roboto_admin_only
  • Restricted tokens cannot call this endpoint
Authorizations:
http
path Parameters
name
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

users

Create, read, and modify entities within Roboto's 'users' domain

get_current_user

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_user

Access control

  • roboto_admin_only
  • deny_actions
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
user_id
required
string (User Id)
Name (string) or Name (null) (Name)
Default: null
is_service_user
boolean (Is Service User)
Default: false
is_system_user
boolean (Is System User)
Default: false
Picture Url (string) or Picture Url (null) (Picture Url)
Default: null
Array of Default Notification Channels (strings) or Default Notification Channels (null) (Default Notification Channels)
Default: ["email"]
Array of Default Notification Types (strings) or Default Notification Types (null) (Default Notification Types)
Default: ["comment_mention"]

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "name": null,
  • "is_service_user": false,
  • "is_system_user": false,
  • "picture_url": null,
  • "default_notification_channels": [
    ],
  • "default_notification_types": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_user

Access control

  • deny_actions
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Name (string) or Name (null) (Name)
Default: null
Picture Url (string) or Picture Url (null) (Picture Url)
Default: null
Notification Channels Enabled (object) or Notification Channels Enabled (null) (Notification Channels Enabled)
Default: null
Notification Types Enabled (object) or Notification Types Enabled (null) (Notification Types Enabled)
Default: null

Responses

Request samples

Content type
application/json
{
  • "name": null,
  • "picture_url": null,
  • "notification_channels_enabled": null,
  • "notification_types_enabled": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_user

Access control

  • deny_actions
  • Restricted tokens cannot call this endpoint
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

get_user_by_id

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
user_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_invites_for_user

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

list_orgs

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

get_org_roles_for_user

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

whoami

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

views

Create, read, and modify entities within Roboto's 'views' domain

list_views_for_org

Page the caller's org for one target, returning only the Views they may see.

Visibility lives in OpenFGA rather than in a column, so it cannot be a WHERE clause the way query_layouts_for_org filters on accessibility. A page of rows is read first and then narrowed with a batch check, the same shape workspaces_service uses.

That check runs after LIMIT, so a page shrinks on the way out — and with Views private by default, most of a page being dropped is the ordinary case rather than the edge. An author with thirty private Views and twenty shared ones would get arbitrarily short pages, and a client paging until it saw fewer rows than it asked for would stop in the middle of the list. So this reads repeatedly until it can hand back a full page.

Each read asks for only the shortfall it still has to cover. A page can only shrink under filtering, so that is as much over-fetching as is ever useful, and it makes overshoot impossible — which matters because the page token is an offset over rows: truncating an oversized read would drop rows the token has already counted, and they would never be seen again. The token returned is the one belonging to the last read actually made.

Reading on is bounded by MAX_PAGE_FILL_READS; see it for why filling is best-effort.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
query Parameters
target
required
string
string or null
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_view

Save a View in the caller's org, private unless the request asks for org-wide visibility.

Authorization lives in :meth:ViewsService.create_for, shared with the chat's View tools.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
name
required
string (Name) [ 1 .. 120 ] characters
target
required
string (QueryTarget)
Enum: "collections" "datasets" "devices" "files" "sessions" "topics" "topic_message_paths" "events"

The type of resource a specific query is requesting.

required
object (ViewDefinition)

The saved contents of a View: what its author searched for, and how they were shown it.

Stored as JSON, with no schema constraint behind it: this model is the only thing enforcing the shape.

A View records intent, not a query. It holds what the author expressed — filter controls or RoboQL text — and the client rebuilds an executable query from that on load. It does not hold a ready-made :class:~roboto.query.QuerySpecification, because one cannot be stored faithfully: Comparator has no way to say "the last 7 days", so translating a relative date filter resolves it to fixed instants. A stored query would show the week the View was saved forever after, presented as though it were live.

Intent is nonetheless recorded in a typed form — :class:~roboto.query.SavedFilters — so that anything able to call the API can create a View, not only a client that already knows how a filter control is shaped. A filter-backed View still has to be translated into a query before it runs, and the Roboto web app is what does that; a RoboQL View needs no translation, since its text runs anywhere.

A View's search target is not part of this definition. The View itself carries it, and repeating it here would let the two disagree.

visibility
string (ViewVisibility)
Default: "private"
Enum: "private" "organization"

Who a View is visible to: asked for when it is created, reported when it is read.

Governs who can see a View, never who can change it. An organization View is readable by the whole org and still editable only by its author, anyone granted editor on it, and org admins.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "target": "collections",
  • "definition": {
    },
  • "visibility": "private"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_view_by_id

Read one View, together with who else can see it.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
view_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_view

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
view_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Name (string) or Name (null) (Name) [ 1 .. 120 ] characters
ViewDefinition (object) or Definition (null) (Definition)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "definition": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

delete_view

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
view_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": null
}

get_view_access

Who can see, edit, and delete this View.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
view_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

edit_view_access

Grant or revoke access to a View.

Adding and removing are authorized separately, following edit_collection_access: a request doing both must satisfy both, and one doing neither is a no-op that needs neither.

Unlike edit_collection_access, the gate also depends on which relation is being changed. associated_group is not an ordinary grant — the org's all-members group carries can_view_views, so adding or removing it is what makes a View org-visible or private, and that is reserved to the author. Every other editable relation stays on can_add_access / can_remove_access, which is what lets an editor hand out access, edit rights included, without also controlling who can see the View.

Gating the whole call on can_change_accessibility would not work: one request may mix an ordinary grant with a sharing change, and an editor has to keep being able to make the former. So the two are checked independently and a request needs whichever apply to it.

Authorizing here rather than in the service means a request that fails any of these checks writes nothing. generic_edit_access applies its adds before it validates the removes, so a partially-authorized request must not reach it.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
view_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
Array of objects (Add)
Array of objects (Remove)

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

duplicate_view

Copy an existing View, with the caller as the new one's author.

Server-side rather than a client-side create-from-existing so the definition is copied whole. A client that duplicated by reading and re-posting would silently drop any field of the definition blob its own version does not understand, which matters because the blob is versioned and the frontend lags the backend across a deploy.

Requires only can_view on the source: duplicating reads it and writes something new, leaving the original untouched. The copy is a fresh View authored by the caller, so it carries none of the source's relations.

That includes its visibility, which is why private is passed explicitly below rather than left to the default: copying a teammate's shared View must not re-publish it to the org under the caller's name, and this route is gated on can_view alone — sharing is reserved to a View's author, through the access endpoint. Stating it here means the property survives a later change of default.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
view_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
One of
name
required
string (Name) [ 1 .. 120 ] characters
target
required
string (QueryTarget)
Enum: "collections" "datasets" "devices" "files" "sessions" "topics" "topic_message_paths" "events"

The type of resource a specific query is requesting.

required
object (ViewDefinition)

The saved contents of a View: what its author searched for, and how they were shown it.

Stored as JSON, with no schema constraint behind it: this model is the only thing enforcing the shape.

A View records intent, not a query. It holds what the author expressed — filter controls or RoboQL text — and the client rebuilds an executable query from that on load. It does not hold a ready-made :class:~roboto.query.QuerySpecification, because one cannot be stored faithfully: Comparator has no way to say "the last 7 days", so translating a relative date filter resolves it to fixed instants. A stored query would show the week the View was saved forever after, presented as though it were live.

Intent is nonetheless recorded in a typed form — :class:~roboto.query.SavedFilters — so that anything able to call the API can create a View, not only a client that already knows how a filter control is shaped. A filter-backed View still has to be translated into a query before it runs, and the Roboto web app is what does that; a RoboQL View needs no translation, since its text runs anywhere.

A View's search target is not part of this definition. The View itself carries it, and repeating it here would let the two disagree.

visibility
string (ViewVisibility)
Default: "private"
Enum: "private" "organization"

Who a View is visible to: asked for when it is created, reported when it is read.

Governs who can see a View, never who can change it. An organization View is readable by the whole org and still editable only by its author, anyone granted editor on it, and org admins.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "target": "collections",
  • "definition": {
    },
  • "visibility": "private"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

viz

Create, read, and modify entities within Roboto's 'viz' domain

query_workspace_events

Specialized, viz-only query for the events relevant to a workspace.

Takes the workspace's data sources (datasets and loose files) and returns every event within their scope; see :py:class:WorkspaceEventsRequest. Like the rest of the event read path, results are filtered to the events the caller can view.

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
dataset_ids
Array of strings (Dataset Ids)
file_ids
Array of strings (File Ids)
Page Token (string) or Page Token (null) (Page Token)
Default: null

Responses

Request samples

Content type
application/json
{
  • "dataset_ids": [
    ],
  • "file_ids": [
    ],
  • "page_token": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

create_workspace

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Config)

Responses

Request samples

Content type
application/json
{
  • "config": { }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_workspace

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
workspace_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_workspace

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
workspace_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
required
object (Config)

Responses

Request samples

Content type
application/json
{
  • "config": { }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

get_workspace_accessibility

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
workspace_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

update_workspace_accessibility

Access control

  • Restricted tokens need the API scope api.everything_else
Authorizations:
http
path Parameters
workspace_id
required
string
header Parameters
X-Roboto-Org-Id
string
X-Roboto-User-Id
string
Request Body schema: application/json
accessibility
required
string (WorkspaceAccessibilityLevel)
Enum: "public" "restricted"

The accessibility level of a single resource (workspace or dataset).

Responses

Request samples

Content type
application/json
{
  • "accessibility": "public"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}