Skip to content
Roboto
Esc
↑↓navigate↵open⌘Jpreview

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
POST/v1/views/create
Authorization
AuthorizationBearer token · headerrequired
Header parameters
X-Roboto-Org-Idstring
X-Roboto-User-Idstring
Request body
requiredapplication/json
namestringrequired
min length 1 · max length 120
targetQueryTargetrequired

The type of resource a specific query is requesting.

Allowed:collectionsdatasetsdevicesfilessessionstopicstopic_message_pathsevents
definitionViewDefinitionrequired

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.

Show properties
schemestring
default: "view_v1"
roboqlstring | null
default: null
Show properties
Any of:
string
string
null
null
filtersSavedFilters | null
default: null
Show properties
Any of:
SavedFilters
filtersStringFilter | NumericFilter | MetricFilter | DateFilter | BooleanFilter | SetFilter | EnumFilter | IdentityFilter[]
Show properties
Array of StringFilter | NumericFilter | MetricFilter | DateFilter | BooleanFilter | SetFilter | EnumFilter | IdentityFilter
One of:
StringFilter
fieldstringrequired
typestring
default: "string"
comparatorstringrequired
Allowed:EQUALSNOT_EQUALSCONTAINSNOT_CONTAINSLIKENOT_LIKEIS_NULLIS_NOT_NULL
valuesstring[]
NumericFilter
fieldstringrequired
typestring
default: "numeric"
comparatorstringrequired
Allowed:EQUALSNOT_EQUALSGREATER_THANLESS_THANGREATER_THAN_OR_EQUALLESS_THAN_OR_EQUALIS_NULLIS_NOT_NULL
valuesnumber[]
MetricFilter
fieldstringrequired
matches ^metric\..+
typestring
default: "metric"
unitstring | null
default: null
Show properties
Any of:
string
string
null
null
comparatorstringrequired
Allowed:EQUALSNOT_EQUALSGREATER_THANLESS_THANGREATER_THAN_OR_EQUALLESS_THAN_OR_EQUALIS_NULLIS_NOT_NULL
valuesnumber[]
DateFilter
fieldstringrequired
typestring
default: "date"
comparatorstringrequired
Allowed:LESS_THANGREATER_THANIS_NULLIS_NOT_NULLBETWEENTODAYLAST_3_HOURSLAST_8_HOURSLAST_24_HOURSLAST_7_DAYSLAST_30_DAYSLAST_90_DAYSTHIS_MONTH
valuesstring[]
BooleanFilter
fieldstringrequired
typestring
default: "boolean"
comparatorstringrequired
Allowed:EQUALSIS_NULLIS_NOT_NULL
valuesboolean[]
SetFilter
fieldstringrequired
typestring
default: "set"
comparatorstringrequired
Allowed:CONTAINSNOT_CONTAINS
valuesstring[]
EnumFilter
fieldstringrequired
typestring
default: "enum"
comparatorstringrequired
Allowed:EQUALSNOT_EQUALSIS_NULLIS_NOT_NULL
valuesstring[]
IdentityFilter
fieldstringrequired
typestring
default: "identity"
comparatorstringrequired
Allowed:IS_USERIS_DEVICEIS_INVOCATIONIS_INTEGRATIONIS_ORGIS_ANY_USERIS_ANY_DEVICEIS_ANY_INVOCATIONIS_ANY_INTEGRATIONIS_ANY_ORG
valuesLabeledOption[]
Show properties
Array of LabeledOption
valuestringrequired
labelstringrequired
match_modeFilterMatchMode

How separate filters combine.

Allowed:ANDOR
null
null
displayViewDisplay

How a View presents its results: which columns, in what order, sorted how, how many rows.

Presentation state only. Nothing here changes which records match.

Show properties
visible_columnsstring[]
sort_bystring | null
default: null
Show properties
Any of:
string
string
null
null
sort_directionSortDirection | null
default: null
Show properties
Any of:
SortDirection
string
null
null
page_sizeinteger | null
default: null
Show properties
Any of:
integer
integer
null
null
visibilityViewVisibility

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.

Allowed:privateorganization
Responses
200

OK

dataobjectrequired

A wire-transmissible representation of a View.

A View is a named, org-scoped, shareable search over one resource type. Who may see or edit it is held in the authorization service rather than in the table this record is read from. :attr:visibility is the one part of that answer carried here, because a client cannot otherwise separate a caller's own Views from their team's without a request per row; every finer-grained grant stays behind the access endpoint.

Show properties
view_idstringrequired
namestringrequired
org_idstringrequired
targetQueryTargetrequired

The type of resource a specific query is requesting.

Allowed:collectionsdatasetsdevicesfilessessionstopicstopic_message_pathsevents
definitionViewDefinitionrequired

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.

Show properties
schemestring
default: "view_v1"
roboqlstring | null
default: null
Show properties
Any of:
string
string
null
null
filtersSavedFilters | null
default: null
Show properties
Any of:
SavedFilters
filtersStringFilter | NumericFilter | MetricFilter | DateFilter | BooleanFilter | SetFilter | EnumFilter | IdentityFilter[]
Show properties
Array of StringFilter | NumericFilter | MetricFilter | DateFilter | BooleanFilter | SetFilter | EnumFilter | IdentityFilter
One of:
StringFilter
fieldstringrequired
typestring
default: "string"
comparatorstringrequired
Allowed:EQUALSNOT_EQUALSCONTAINSNOT_CONTAINSLIKENOT_LIKEIS_NULLIS_NOT_NULL
valuesstring[]
NumericFilter
fieldstringrequired
typestring
default: "numeric"
comparatorstringrequired
Allowed:EQUALSNOT_EQUALSGREATER_THANLESS_THANGREATER_THAN_OR_EQUALLESS_THAN_OR_EQUALIS_NULLIS_NOT_NULL
valuesnumber[]
MetricFilter
fieldstringrequired
matches ^metric\..+
typestring
default: "metric"
unitstring | null
default: null
Show properties
Any of:
string
string
null
null
comparatorstringrequired
Allowed:EQUALSNOT_EQUALSGREATER_THANLESS_THANGREATER_THAN_OR_EQUALLESS_THAN_OR_EQUALIS_NULLIS_NOT_NULL
valuesnumber[]
DateFilter
fieldstringrequired
typestring
default: "date"
comparatorstringrequired
Allowed:LESS_THANGREATER_THANIS_NULLIS_NOT_NULLBETWEENTODAYLAST_3_HOURSLAST_8_HOURSLAST_24_HOURSLAST_7_DAYSLAST_30_DAYSLAST_90_DAYSTHIS_MONTH
valuesstring[]
BooleanFilter
fieldstringrequired
typestring
default: "boolean"
comparatorstringrequired
Allowed:EQUALSIS_NULLIS_NOT_NULL
valuesboolean[]
SetFilter
fieldstringrequired
typestring
default: "set"
comparatorstringrequired
Allowed:CONTAINSNOT_CONTAINS
valuesstring[]
EnumFilter
fieldstringrequired
typestring
default: "enum"
comparatorstringrequired
Allowed:EQUALSNOT_EQUALSIS_NULLIS_NOT_NULL
valuesstring[]
IdentityFilter
fieldstringrequired
typestring
default: "identity"
comparatorstringrequired
Allowed:IS_USERIS_DEVICEIS_INVOCATIONIS_INTEGRATIONIS_ORGIS_ANY_USERIS_ANY_DEVICEIS_ANY_INVOCATIONIS_ANY_INTEGRATIONIS_ANY_ORG
valuesLabeledOption[]
Show properties
Array of LabeledOption
valuestringrequired
labelstringrequired
match_modeFilterMatchMode

How separate filters combine.

Allowed:ANDOR
null
null
displayViewDisplay

How a View presents its results: which columns, in what order, sorted how, how many rows.

Presentation state only. Nothing here changes which records match.

Show properties
visible_columnsstring[]
sort_bystring | null
default: null
Show properties
Any of:
string
string
null
null
sort_directionSortDirection | null
default: null
Show properties
Any of:
SortDirection
string
null
null
page_sizeinteger | null
default: null
Show properties
Any of:
integer
integer
null
null
schema_versionintegerrequired
createdstring<date-time>required
created_bystringrequired
modifiedstring<date-time>required
modified_bystringrequired
visibilityViewVisibility | null
default: null
Show properties
Any of:
ViewVisibility
string
null
null
400

Thrown when the conversation context (messages, system prompt, tool results) exceeds the model's context window limit.

The token estimate and the model's context limit are not carried on the exception, so a caller cannot read usage numbers off it.

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
401

Thrown when authentication fails

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
403

Thrown if an operation would exceed a user or org level limit.

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
404

Thrown if a user is attempting to perform an action unrecognized by the Roboto platform.

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
409

Thrown if there is a conflict between a resource you're creating and another existing resource

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
410

Thrown if a resource is missing or expired.

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
500

An error the platform reported that this SDK release cannot resolve to a specific exception class.

Reported for an element of a :py:class:~roboto.http.BatchResponse whose error names a code this release defines no class for, or that arrived without a code, without a message, or as text that is not an error envelope at all. It carries whatever code and message the platform sent, so a caller handling the failure still learns what went wrong; when no message could be read, the message is the error's raw text.

The error envelope carries no status code, so http_status_code reports the 500 inherited from :py:class:RobotoDomainException rather than the status the failure actually had.

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
501

Thrown by shimmed out APIs which have not yet been implemented

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
503

Thrown when a service is unavailable, such as when it's under heavy load and can't accept new requests. This is expected to be transient and ought to be retried.

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
504

Thrown when the service times out while processing a request. This is exepcted to be transient and ought to be retried.

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
507

Thrown when the server cannot complete the request because the response payload exceeds a storage or transport capacity limit (e.g., Lambda response size). This is NOT expected to be transient and should NOT be retried.

errorobject
Show properties
error_codenumber
messagestring
stack_tracestring | null
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.roboto.ai/v1/views/create' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "target": "collections",
  "definition": {
    "scheme": "view_v1",
    "roboql": null,
    "filters": null,
    "display": {
      "visible_columns": [
        "string"
      ],
      "sort_by": null,
      "sort_direction": null,
      "page_size": null
    }
  },
  "visibility": "private"
}'
Response
{
  "data": {
    "view_id": "string",
    "name": "string",
    "org_id": "string",
    "target": "collections",
    "definition": {
      "scheme": "view_v1",
      "roboql": null,
      "filters": null,
      "display": {
        "visible_columns": [
          "string"
        ],
        "sort_by": null,
        "sort_direction": null,
        "page_size": null
      }
    },
    "schema_version": 0,
    "created": "2019-08-24T14:15:22Z",
    "created_by": "string",
    "modified": "2019-08-24T14:15:22Z",
    "modified_by": "string",
    "visibility": null
  }
}