Skip to content
Omniglass Omniglass Omniglass

Create an interface

POST
/interfaces
 
curl --request POST \
  --url https://example.com/api/v1/interfaces \
  --header 'Content-Type: application/json' \
  --data '{ "component": "example", "interface_type": "example", "label": "example", "node": "example", "params": "example" }'

Creates an interface owned by a component (or a server-hosted one, which needs an all-scoped grant), named by its protocol; the optional label is the only identity string an operator types, and is where what the connection is FOR goes. The create scope cascades through the owning component. Gated by interface:create.

Request Body required

Section titled “Request Body required ”
Media type application/json
object
$schema

A URL to the JSON Schema for this object.

string format: uri
component

Owning component, by name or id; omit for a server-hosted interface (needs an all-scoped grant)

string
interface_type
required

An interface_type name (the protocol); the interface is named by it, unique within the component

string
>= 1 characters
label

What an operator reads in lists (Control processor). Settable here because the name is derived from the type, so it says how the device is reached and never what the connection is for

string
<= 200 characters
node

Node placement, by name or id

string
params

Endpoint/target settings (jsonb)

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Created

Media type application/json
object
$schema

A URL to the JSON Schema for this object.

string format: uri
component

The owning component name; absent for a server-hosted interface

string
component_id

The owning component’s id; the stable form of component

string
id
required

The interface’s surrogate id (the address)

string
interface_type
required

The interface_type name (the protocol)

string
interface_type_id
required

The interface_type’s uuid, the stable form of interface_type

string
label

The friendly string an operator reads, and the only identity string an operator types here: the name is derived from the type. Absent when unset, and a surface with none renders the name verbatim

string
name
required

The derived name (its protocol), unique within the owning component

string
node

The node placement name, if assigned

string
node_id

The placed node’s id; the stable form of node

string
params

The endpoint/target settings (jsonb)

Example 
{
  "$schema": "/api/v1/schemas/InterfaceBody.json"
}

default

Section titled “default ”

Error

Media type application/problem+json
object
$schema

A URL to the JSON Schema for this object.

string format: uri
detail

A human-readable explanation specific to this occurrence of the problem.

string
errors

Optional list of individual error details

Array<object> | null
object
location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string
message

Error message text

string
value

The value at the given location

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri
status

HTTP status code

integer format: int64
title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string
type

A URI reference to human-readable documentation for the error.

string format: uri
default: about:blank
Example 
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}