Data Schemas

Learn the common data structures.

Subscription

An Ocelloids subscription allows users to subscribe to the available agents , tailoring data filters and delivery channels. Each subscription is linked to an agent, which handles data collection and processing to provide curated information.

Data Structure

Property	Description	Required	Example
id	The unique user provided subscription ID.¹	yes	my-unique-id
agent	The agent identifier to subcribe to².	yes	informant
args	The agent input arguments for the subscription².	yes	-
channels	The delivery channels array.	yes	-
ephemeral	Whether the subscription is ephemeral or persistent.	no	-
public	Whether the subscription is shared publicly.	no	-

Subscription OpenAPI Schema

{
  "type":"object",
  "properties":{
    "id":{
      "type":"string",
      "minLength":1,
      "maxLength":100,
      "pattern":"[A-Za-z0-9.\\-_]+"
    },
    "agent":{
      "type":"string",
      "minLength":1,
      "maxLength":100,
      "pattern":"[A-Za-z0-9.\\-_]+"
    },
    "args":{
      "type":"object",
      "additionalProperties":{
        
      }
    },
    "ephemeral":{
      "type":"boolean"
    },
    "public":{
      "type":"boolean"
    },
    "channels":{
      "type":"array",
      "items":{
        "anyOf":[
          {
            "type":"object",
            "properties":{
              "type":{
                "type":"string",
                "enum":[
                  "webhook"
                ]
              },
              "url":{
                "type":"string",
                "minLength":5,
                "maxLength":2000,
                "pattern":"https?:\\/\\/.*"
              },
              "contentType":{
                "type":"string",
                "pattern":"(?:application|text)\\/[a-z0-9-+.]+",
                "maxLength":250
              },
              "template":{
                "type":"string",
                "minLength":5,
                "maxLength":32000
              },
              "bearer":{
                "type":"string",
                "minLength":1,
                "maxLength":1000
              },
              "secret":{
                "type":"string",
                "minLength":1,
                "maxLength":1000
              },
              "limit":{
                "type":"number",
                "minimum":0,
                "maximum":9007199254740991
              }
            },
            "required":[
              "type",
              "url"
            ],
            "additionalProperties":false
          },
          {
            "type":"object",
            "properties":{
              "type":{
                "type":"string",
                "enum":[
                  "log"
                ]
              }
            },
            "required":[
              "type"
            ],
            "additionalProperties":false
          },
          {
            "type":"object",
            "properties":{
              "type":{
                "type":"string",
                "enum":[
                  "websocket"
                ]
              }
            },
            "required":[
              "type"
            ],
            "additionalProperties":false
          }
        ]
      },
      "minItems":1
    }
  },
  "required":[
    "id",
    "agent",
    "args",
    "channels"
  ],
  "additionalProperties":false
}

Delivery Channels

Hint

You can configure multiple channels, such as multiple webhooks and WebSocket access, within the same subscription.

Ocelloids subscriptions support multiple delivery channels for notifications, allowing you to receive real-time updates in the most convenient way for your application.

Webhook Delivery Channel

Data Structure

These are the properties you can specify in the webhook delivery channel.

Propery	Description	Required	Default
type	Type of notification channel. Always set to “webhook”.	Yes	n/a
url	Webhook endpoint URL.	Yes	-
contentType	Content type of the resource.	No	application/json
events	Overrides subscription level filter for event types in notification.	No	-
template	Template to be applied to notification messages before delivery³.	No	-
bearer	Bearer token for webhook authentication. It will be posted as Authorization header to your endpoint.	No	-
secret	Secret for verification of HMAC signatures.	No	-
limit	Maximum number of retries in case of delivery error.	No	5

WebSocket Delivery Channel

Data Structure

Propery	Description	Required	Default
type	Type of notification channel. Always set to “websocket”.	Yes	n/a

Identifiers for persistent subscriptions are provided by the client and must be unique within the context of each agent. You can use a common prefix as a namespace for your subscriptions to avoid identifier conflicts. ↩︎
See Agents documentation . ↩︎ ↩︎
See Webhooks templates documentation . ↩︎