Events

Stream project events

Required scope: events:listen

Opens a server-sent event (SSE) stream of this project’s events. Every event frame carries the same event object as the events API and the exact webhook body when it is available.

Send Accept: text/event-stream. Resume after a disconnect by sending the last received cursor as Last-Event-ID or cursor. Cursors are valid for 24 hours and are bound to the organization, project and types filter.

With ack=auto (default), each event is released as soon as it is written. With ack=manual, at most maxInFlight events are outstanding until you acknowledge them; unacknowledged events produce a backpressure frame and then a dropped frame.

The stream sends a heartbeat frame every heartbeatIntervalMs. It closes with revoked within one heartbeat after the credential, project or feature access ends, and with expiry at connectionExpiresAt or after idleTimeoutMs without an event. Reconnect from the last cursor after expiry, dropped or a recoverable gap.

Requires events:listen and the Event streams beta. Organization API keys and project tokens are accepted; client tokens are rejected.

GET

platform

projects

{projectId}

events

stream

Stream project events

curl --request GET \
  --url https://api.polymorfa.com/platform/projects/{projectId}/events/stream \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.polymorfa.com/platform/projects/{projectId}/events/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.polymorfa.com/platform/projects/{projectId}/events/stream"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polymorfa.com/platform/projects/{projectId}/events/stream"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "v": 1,
  "streamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sequence": 2,
  "sentAt": "2023-11-07T05:31:56Z",
  "type": "ready",
  "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "connectionExpiresAt": "2023-11-07T05:31:56Z",
  "heartbeatIntervalMs": 123,
  "maxInFlight": 123,
  "ack": "auto",
  "types": [
    "<string>"
  ],
  "idleTimeoutMs": 123,
  "resume": {
    "startPosition": "now",
    "acceptedCursor": "<string>",
    "oldestAvailableCursor": "<string>",
    "cursorExpiresAt": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

Authorizations

Authorization

string

header

required

Send your team API key or project token as Authorization: Bearer <token>. The credential must have the required permissions. Project tokens can access only their own project.

Headers

Last-Event-ID

string

Identifier for the last event.

Value constraints

Constraint	Accepted input
String length	At most `4096` characters
Resume cursor sent automatically by SSE clients after a reconnect.

Maximum string length: 4096

Path Parameters

projectId

string<uuid>

required

Identifier of the Polymorfa project that owns this resource.

Value constraints

Constraint	Accepted input
Format	`uuid`

Query Parameters

types

string

Specifies types for this query parameter. Comma-separated event types to include, or repeat the parameter. A trailing * matches a prefix, such as message.*. Omit for every type. At most 32 filters.

Example:

"message.*,session.connected"

cursor

string

Specifies cursor for this query parameter.

Value constraints

Constraint	Accepted input
String length	At most `4096` characters
Resume after this cursor. Equivalent to `Last-Event-ID`; if both are sent they must match.

Maximum string length: 4096

ack

enum<string>

Specifies ack for this query parameter.

Allowed values

Value	Meaning
`auto`	Auto.
`manual`	Manual.
`auto` (default) releases events once written. `manual` holds them until acknowledged.

Available options:

auto,

manual

Response

An SSE stream. The first frame is ready. revoked, expiry, dropped and gap frames end the connection, except a gap with reason retention_exceeded, which reports skipped events and the stream continues.

JSON carried in the data field of one SSE message. The SSE event field repeats type.

enum<number>

required

Specifies v for this management platform access event stream ready frame.

Allowed values

Value	Meaning
`1`	1.

Available options:

1

streamId

string<uuid>

required

Identifier for the stream.

Value constraints

Constraint	Accepted input
Format	`uuid`

sequence

integer

required

Frame counter for this connection. It restarts at 1 on every connection.

Value constraints

Constraint	Accepted input
Numeric value	`1` or greater

Required range: x >= 1

sentAt

string<date-time>

required

Timestamp for sent at.

Value constraints

Constraint	Accepted input
Format	`date-time`

type

enum<string>

required

Type discriminator for this object.

Allowed values

Value	Meaning
`ready`	Ready.

Available options:

ready

projectId

string<uuid>

required

Identifier of the Polymorfa project that owns this resource.

Value constraints

Constraint	Accepted input
Format	`uuid`

connectionExpiresAt

string<date-time>

required

Timestamp for connection expires at.

Value constraints

Constraint	Accepted input
Format	`date-time`

heartbeatIntervalMs

integer

required

Specifies heartbeat interval ms for this management platform access event stream ready frame.

maxInFlight

integer

required

Specifies max in flight for this management platform access event stream ready frame.

ack

enum<string>

required

Specifies ack for this management platform access event stream ready frame.

Allowed values

Value	Meaning
`auto`	Auto.
`manual`	Manual.

Available options:

auto,

manual

types

string[]

required

Types associated with this management platform access event stream ready frame.

idleTimeoutMs

integer

required

Specifies idle timeout ms for this management platform access event stream ready frame.

resume

object

required

Structured resume values for this management platform access event stream ready frame.

Show child attributes

Stream project events

curl --request GET \
  --url https://api.polymorfa.com/platform/projects/{projectId}/events/stream \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.polymorfa.com/platform/projects/{projectId}/events/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.polymorfa.com/platform/projects/{projectId}/events/stream"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polymorfa.com/platform/projects/{projectId}/events/stream"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "v": 1,
  "streamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sequence": 2,
  "sentAt": "2023-11-07T05:31:56Z",
  "type": "ready",
  "projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "connectionExpiresAt": "2023-11-07T05:31:56Z",
  "heartbeatIntervalMs": 123,
  "maxInFlight": 123,
  "ack": "auto",
  "types": [
    "<string>"
  ],
  "idleTimeoutMs": 123,
  "resume": {
    "startPosition": "now",
    "acceptedCursor": "<string>",
    "oldestAvailableCursor": "<string>",
    "cursorExpiresAt": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

Overview

Messaging API

Platform API

Graph API

Webhook events

Stream project events

Authorizations

Headers

Path Parameters

Query Parameters

Response