Sessions

Quick Navigation

• What is a session?
• Core Concepts
  • Session resource
  • Session statuses
  • Pagination
  • Session identifiers and masking
  • Current step and assignees
• How-To Guides
  • List sessions
  • Get a session by ID
  • Share a session
  • Cancel a running session
  • Delete a session
• Error responses

What is a session?

A session is a single running instance of a workflow. When you start a workflow, Streamline creates a session that progresses through the workflow's steps, collects data, and tracks who is responsible for each step. Sessions are how you turn a saved workflow definition into live work.

You can list sessions for your organization, inspect a single session's current state, share a link to a session with the people who need to act on it, and stop or remove sessions you no longer need. The endpoints below cover these operations; base URL and authentication match the rest of the Streamline API.

Core Concepts

Session resource

Responses from the list and get-session endpoints share the same session shape. The table below describes the fields you will see.

Session statuses

A session's status field uses one of the following values:

• ASSIGNED — The session has been started and is waiting for action on the current step.
• RUNNING — The session is actively progressing through its steps.
• COMPLETED — The session finished successfully.
• CANCELLED — The session was cancelled before completing.
• EXPIRED — The session expired before completing.
• FAILED — The session ended in a failure state.
• TERMINATED — The session was terminated.

When filtering by status, send the value exactly as shown above (for example statuses=COMPLETED,RUNNING).

Pagination

The list endpoint uses page-based pagination. You must set pagination=page and then use pageNumber (1-indexed) and pageSize to control the page you receive. The response includes a page object with the actual counts so you can iterate.

The page object in the response contains:

Session identifiers and masking

A workflow may be configured to give each session a human-readable name (for example "Onboarding — Jane Doe"). When that configuration exists, sessionIdentifierConfigured is true and sessionName carries the resolved name.

By default, session names are masked in list responses to protect personally identifiable information. To receive unmasked names, pass revealSessionIdentifiers=true. Revealing identifiers requires the admin permission or to be configured on the project level; the response includes canViewSessionIdentifiers: true when the authenticated user is allowed to see unmasked values for the scoped project.

Current step and assignees

When a session is in progress, currentStep describes the step the session is currently on and the people responsible for acting on it.

Each entry in assignees describes one person or group responsible for the step:

Assignee status uses one of: PENDING, ASSIGNED, WAITING, CLAIMED, IN_PROGRESS, COMPLETED, DECLINED, EXPIRED, CANCELLED, FAILED, REASSIGNED, NOT_COMPLETED.

How-To Guides

Let's explore common scenarios for managing sessions.

List sessions

Use get sessions to retrieve a paginated list of sessions for your organization.

GET /v1/sessions

{
  "content": [
    {
      "id": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
      "workflowId": "w1b2c3d4-e5f6-7890-1234-567890abcdef",
      "projectId": "p1b2c3d4-e5f6-7890-1234-567890abcdef",
      "status": "RUNNING",
      "completedAt": null,
      "createdAt": "2026-08-01T09:30:00.000Z",
      "versionName": "Employee Onboarding v2",
      "sessionName": "Onboarding — Jane Doe",
      "sessionIdentifierConfigured": true,
      "currentStep": {
        "id": "s1b2c3d4-e5f6-7890-1234-567890abcdef",
        "name": "Form",
        "type": "forms",
        "resourceId": null,
        "startedAt": "2026-08-01T09:30:00.000Z",
        "assignees": [
          {
            "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
            "taskId": "t1b2c3d4-e5f6-7890-1234-567890abcdef",
            "type": "EXTERNAL",
            "role": null,
            "status": "ASSIGNED",
            "isCompleter": false,
            "isInPerson": false,
            "name": "Jane Doe",
            "email": "[email protected]",
            "phoneNumber": null,
            "userId": null,
            "groupId": null,
            "assignedAt": "2026-08-01T09:30:00.000Z",
            "allowClaiming": false,
            "allowReassignment": true,
            "destinationUrl": "https://us.streamline.intellistack.ai/tasks/assignee/t1b2c3d4-e5f6-7890-1234-567890abcdef"
          }
        ]
      }
    }
  ],
  "page": {
    "size": 1,
    "pageNumber": 1,
    "pageSize": 20,
    "totalElements": 1,
    "totalPages": 1
  },
  "canViewSessionIdentifiers": true
}

One things to note:

• When revealSessionIdentifiers is omitted or false, session names are masked. canViewSessionIdentifiers is included only when the user is authorized to reveal identifiers for the scoped project.

Get a session by ID

Use get session to retrieve a single session by its id.

GET /v1/sessions/{sessionId}

The response has the same shape as a single item from the list response. See Session resource for the field reference and Current step and assignees for the nested currentStep shape.

Share a session

Use share session to send a session link to one or more recipients by email or SMS.

POST /v1/sessions/{sessionId}/share

The request body contains a data object discriminated by type:

When data.type is email:

When data.type is sms:

A successful share returns 204 No Content.

{
  "data": {
    "type": "email",
    "emails": ["[email protected]", "[email protected]"],
    "subject": "Your review is needed",
    "message": "Please complete the onboarding steps when you have a moment.",
    "buttonText": "Open session"
  }
}

For SMS, send data.type sms with a phoneNumbers array (and an optional message) instead.

Cancel a running session

Use cancel session to stop a session that is still running.

POST /v1/sessions/{sessionId}/cancel

A successful cancel returns 204 No Content.

Delete a session

Use delete session to remove a session from your lists.

POST /v1/sessions/{sessionId}/delete

A successful delete returns 204 No Content.