{
  "openapi": "3.1.0",
  "info": {
    "title": "Insights Orbit event API",
    "version": "1",
    "summary": "Read every page view and event a site collected, and send events from your servers.",
    "description": "Two endpoints for your own servers and tools: the raw event API reads what a site collected, and the server API sends events that happen on a server. Both take an Insights Orbit key (ins_live_) as Authorization: Bearer, with the scope to read or to send events. Keep keys on a server, never in a web page or an app.\n\nEach key may read events 60 times a minute and send events 600 times a minute. Over that, the answer is 429 with Retry-After: 60. No other rate limit headers are sent.\n\nErrors are error with a code and a message. No visitor is identified: there is no visitor id, address or browser string in the answers.",
    "contact": {
      "name": "Bifröst Orbit",
      "url": "https://docs.bifrostorbit.com/",
      "email": "hello@bifrostorbit.com"
    },
    "termsOfService": "https://bifrostorbit.com/legal/terms/"
  },
  "servers": [
    {
      "url": "https://api.bifrostorbit.com/insights/v1",
      "description": "Production"
    },
    {
      "url": "https://api-stage.bifrostorbit.com/insights/v1",
      "description": "Staging"
    }
  ],
  "tags": [
    {
      "name": "Raw events",
      "description": "Page views and events, for your own tools."
    },
    {
      "name": "Server events",
      "description": "Events from your servers."
    }
  ],
  "externalDocs": {
    "url": "https://docs.bifrostorbit.com/insights/developers/raw-event-api/",
    "description": "The raw event API guide"
  },
  "paths": {
    "/events": {
      "get": {
        "operationId": "listEvents",
        "tags": [
          "Raw events"
        ],
        "summary": "Read raw events",
        "description": "Every page view and event a site collected, oldest first, for a data warehouse or your own tools. Needs a key that reads events and the Growth plan. 60 requests a minute per key. The newest events can take a few seconds to show up.",
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site's key, from Install.",
            "schema": {
              "type": "string"
            },
            "example": "nw7k2q9x"
          },
          {
            "name": "from",
            "in": "query",
            "description": "A date or a time, such as 2026-10-01. Counts. Without from and to, the last 24 hours.",
            "schema": {
              "type": "string"
            },
            "example": "2026-11-09"
          },
          {
            "name": "to",
            "in": "query",
            "description": "A date or a time. Doesn't count.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Only events with this name, such as Signed up.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "pageview or event.",
            "schema": {
              "type": "string",
              "enum": [
                "pageview",
                "event"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "100 unless you say, at most 1,000.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "next from the page before.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of events, oldest first. When next isn't null there are more: ask again with cursor set to it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    },
                    "next": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Ask again with cursor set to it until it is null."
                    }
                  },
                  "required": [
                    "data",
                    "next"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "6720f1c2a9e4b1d2c3f40b11",
                      "type": "pageview",
                      "name": "pageview",
                      "at": "2026-11-09T08:14:22.000Z",
                      "host": "northwilds.com",
                      "path": "/trips/lofoten-sea-kayaking/",
                      "referrer": "google.com",
                      "channel": "Search",
                      "utm": {},
                      "country": "NO",
                      "device": "mobile",
                      "browser": "Safari",
                      "os": "iOS",
                      "properties": null,
                      "revenue": null,
                      "currency": null,
                      "contentId": "6650f1c2a9e4b1d2c3f40a21",
                      "label": null,
                      "visit": "c1f9a2e4"
                    },
                    {
                      "id": "6720f1c2a9e4b1d2c3f40b12",
                      "type": "event",
                      "name": "Booking started",
                      "at": "2026-11-09T08:16:05.000Z",
                      "host": "northwilds.com",
                      "path": "/trips/lofoten-sea-kayaking/",
                      "referrer": "google.com",
                      "channel": "Search",
                      "utm": {},
                      "country": "NO",
                      "device": "mobile",
                      "browser": "Safari",
                      "os": "iOS",
                      "properties": {
                        "trip": "lofoten-sea-kayaking"
                      },
                      "revenue": null,
                      "currency": null,
                      "contentId": "6650f1c2a9e4b1d2c3f40a21",
                      "label": null,
                      "visit": "c1f9a2e4"
                    }
                  ],
                  "next": "MTc2MjY3NjE2NTAwMF82NzIwZjFjMmE5ZTRiMWQyYzNmNDBiMTI"
                }
              }
            }
          },
          "400": {
            "description": "A date, type or cursor isn't valid (invalid or invalid_cursor).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "from must be before to"
                  }
                }
              }
            }
          },
          "401": {
            "description": "No key, or a key that is wrong or removed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "Send an API key from Insights Orbit as Authorization: Bearer ins_live_…"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key may only send events (wrong_scope), or the plan doesn't include the API (not_in_plan).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_in_plan",
                    "message": "The raw event API is not in your organisation's plan"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No site with that key in your organisation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unknown_site",
                    "message": "There is no site with that key in your organisation"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 60 requests a minute with one key.",
            "headers": {
              "Retry-After": {
                "description": "Always 60: the seconds to wait before trying again.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests. Each key may make 60 a minute."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something went wrong on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Insights Orbit could not take the events"
                  }
                }
              }
            }
          },
          "503": {
            "description": "The event API isn't switched on for this server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_available",
                    "message": "The event API is not set up here yet"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Insights Orbit keys are secret and belong on a server."
        }
      }
    },
    "/server/events": {
      "post": {
        "operationId": "sendServerEvents",
        "tags": [
          "Server events"
        ],
        "summary": "Send events from a server",
        "description": "Events that happen on a server, such as a payment your provider confirms, so they count in goals, revenue and monthly events. Needs a key that sends events. Every plan. While the trial or plan has ended, it answers 204 and stores nothing.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ServerEvents"
              },
              "example": {
                "site": "nw7k2q9x",
                "events": [
                  {
                    "id": "order-1042",
                    "name": "Order paid",
                    "url": "https://northwilds.com/gear/fjell-gtx-boot/",
                    "revenue": 1890,
                    "currency": "NOK",
                    "properties": {
                      "items": 2,
                      "shop": "Oslo"
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Taken.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "accepted": {
                          "type": "integer"
                        },
                        "repeated": {
                          "type": "integer",
                          "description": "Events with an id already sent, counted once."
                        }
                      },
                      "required": [
                        "accepted",
                        "repeated"
                      ]
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "accepted": 1,
                    "repeated": 0
                  }
                }
              }
            }
          },
          "204": {
            "description": "The plan has ended: nothing was stored."
          },
          "400": {
            "description": "The body isn't JSON (invalid_json) or the events aren't valid (invalid_events). The message names the field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid_events",
                    "message": "Those are not events Insights Orbit can take: events.0.currency Invalid input"
                  }
                }
              }
            }
          },
          "401": {
            "description": "No key, or a key that is wrong or removed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "Send an API key from Insights Orbit as Authorization: Bearer ins_live_…"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key may only read events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "wrong_scope",
                    "message": "This key can only read events. Make a key that sends events under API keys."
                  }
                }
              }
            }
          },
          "404": {
            "description": "The site isn't in the key's organisation, or is in the bin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unknown_site",
                    "message": "There is no site with that key in your organisation"
                  }
                }
              }
            }
          },
          "413": {
            "description": "Over 256 KB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "too_large",
                    "message": "Send at most 256 KB at a time"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 600 requests a minute with one key.",
            "headers": {
              "Retry-After": {
                "description": "Always 60: the seconds to wait before trying again.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests. Each key may send 600 a minute."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something went wrong on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Insights Orbit could not take the events"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Insights Orbit keys are secret, and it stores real events."
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal."
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "pageview",
              "event"
            ]
          },
          "name": {
            "type": "string",
            "description": "pageview for a page view."
          },
          "at": {
            "type": "string",
            "description": "When it happened.",
            "format": "date-time"
          },
          "host": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "referrer": {
            "type": [
              "string",
              "null"
            ]
          },
          "channel": {
            "type": "string",
            "description": "Such as Search."
          },
          "utm": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "The campaign tags, when there were any."
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "device": {
            "type": "string",
            "description": "desktop, mobile, tablet, or server for server events."
          },
          "browser": {
            "type": "string"
          },
          "os": {
            "type": "string"
          },
          "properties": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {},
            "description": "Text, numbers or true or false."
          },
          "revenue": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "contentId": {
            "type": [
              "string",
              "null"
            ],
            "description": "The CMS Orbit entry the page belongs to."
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "visit": {
            "type": "string",
            "description": "Events of one visit share it. No visitor is identified."
          },
          "person": {
            "type": "string",
            "description": "With known users on: a scrambled form of the user id, the same for every event of that person."
          }
        },
        "required": [
          "id",
          "type",
          "name",
          "at",
          "host",
          "path",
          "referrer",
          "channel",
          "utm",
          "country",
          "device",
          "browser",
          "os",
          "properties",
          "revenue",
          "currency",
          "contentId",
          "label",
          "visit"
        ]
      },
      "ServerEvents": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "events": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9._:-]{1,80}$",
                  "description": "Your own id, such as the order number. An id already sent for the site in the last eight days is counted once, so you can safely send again."
                },
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120,
                  "description": "The event's name, such as Order paid."
                },
                "timestamp": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                    },
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    }
                  ],
                  "description": "When it happened: a time such as 2026-10-21T09:30:00Z or milliseconds since 1970, up to seven days back. Now when left out."
                },
                "url": {
                  "type": "string",
                  "maxLength": 2048,
                  "format": "uri",
                  "description": "The page it belongs to, on one of the site's addresses."
                },
                "properties": {
                  "type": "object",
                  "propertyNames": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64
                  },
                  "additionalProperties": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 500
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  },
                  "description": "Up to 30 details, each text, a number or true or false."
                },
                "revenue": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Money. Needs currency."
                },
                "currency": {
                  "type": "string",
                  "pattern": "^[A-Z]{3}$",
                  "description": "A three-letter code, such as EUR."
                },
                "userId": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "description": "Your user id for the person, used only with known users on and kept only scrambled."
                },
                "country": {
                  "type": "string",
                  "pattern": "^[A-Z]{2}$",
                  "description": "Two letters, such as DE."
                }
              },
              "required": [
                "name"
              ]
            },
            "description": "One to 100 events. The whole request can be up to 256 KB."
          }
        },
        "required": [
          "site",
          "events"
        ]
      }
    },
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "An Insights Orbit key, ins_live_…, that reads or sends events."
      }
    }
  }
}
