> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List or stream change events (repo_id addressing)
> Users Plugins
**Accepted credentials:** User token, Plugin installation token.
Returns trail events by opaque repo id with the same JSON cursor pagination, category filters, open event catalog, Last-Event-ID SSE resume, and from=head latest-push start as the name-addressed route.
Use an own-account bearer token (including supported service accounts) or a Core-issued plugin installation bearer token, subject to the permissions and restrictions below. Plugin assertion JWTs and plugin OAuth user-delegation tokens are not accepted here.
Requires live repository pull permission (contents:read for plugin installations). Other authorized automation principals can also use this operation. Trails must be enabled. Send requests to the repository’s primary API region. Streams recheck credentials, repository access and placement.
## OpenAPI
````yaml /openapi/generated/trails.json get /repos/{repo_id}/changes/{number}/events
openapi: 3.1.0
info:
description: >-
Unified Entire API gateway. Aggregates the control plane and regional
repository-operation services behind a single endpoint.
title: Entire API
version: 0.1.0
servers:
- url: https://aws-us-east-2.api.entire.io/api/v1
security:
- bearerAuth: []
tags:
- description: Operations under the /search surface.
name: search
- description: Operations under the /semantic-search surface.
name: semantic-search
- description: Operations served by the brainstore service.
name: brainstore
- description: >-
The authenticated caller's own cross-repo activity, commits, checkpoints,
sessions, and recap.
name: me
x-group: Your activity
- description: >-
Residency-aware previews of the caller's surface, served under
/experimental. Shapes may change without notice.
name: experimental
- description: >-
Per-user settings: pinned and recent repos, diff view, and saved filter
tabs.
name: preferences
- description: >-
Repository discovery list, metadata, and headline rollups (summary,
activity, contributors, agents).
name: repos
- description: >-
Git browsing for a repo: commits, commit detail, branch compare, tree
listings, raw file bytes, and branches.
name: code
- description: >-
Checkpoint listing, resolution, LLM analysis, transcripts, and per-repo
checkpoint status.
name: checkpoints
x-group: Checkpoints
- description: >-
Materialised sessions: listing, detail, transcripts, rename, and the
public-share toggle.
name: sessions
x-group: Sessions
- description: >-
Repo dashboard aggregates under /overview: commit and checkpoint stats,
contributor breakdowns, and session patterns.
name: overview
- description: Live ref-change stream for a repo (SSE).
name: refs
x-group: Ref events
- description: >-
Trails themselves: list, create, read, update, delete, plus per-repo
counts, claimed branches, and the body-document ensure.
name: trails
x-group: Trails
- description: >-
What has happened on a trail: the merged timeline, the event stream, and
who is watching (per trail, plus a repo-wide roll-up).
name: trail-activity
x-group: Activity
- description: >-
Conversation on a trail: discussions, their messages, and the live
discussion-event stream.
name: trail-discussions
x-group: Discussions
- description: >-
Code review on a trail: review state, comments, diffs, reviewed files, and
review re-runs.
name: trail-reviews
x-group: Reviews
- description: >-
Runner output on a trail: the latest result per configured runner, monitor
results, and manual launches.
name: trail-runs
- description: >-
Quality gates: repo gate definitions, gate settings, repo-authored monitor
definitions, and a trail's gate evaluation.
name: trail-gates
x-group: Gates
- description: >-
Getting a trail landed: approval decisions, merge readiness, and the merge
itself.
name: trail-approvals
x-group: Approvals
- description: >-
Trail attachment blobs: upload intent, completion, retrieval, and
deletion.
name: trail-attachments
- description: Project-scoped Trails, and their owned repository Changes and discussions.
name: projects
- description: Agent-provenance ranking for a repo's code scopes.
name: experts
x-group: Experts
- description: >-
git-meta-compatible repo metadata read and write (git is the source of
truth).
name: git-meta
- description: >-
A project's versioned agents — what each runs (its own runner or an Entire
preset), what it is called, the environment it runs in, the repositories
it reviews and its trigger — and Entire's presets. Saving one runs
nothing.
name: agents
- description: >-
A project's saved, versioned Environments — where an agent runs: provider
and sandbox lifetime — reusable across the project's repositories and
agents. Configuration only: saving one provisions nothing.
name: environments
- description: >-
Runs of a project's agents, each on one Change: starting one, the
immutable snapshot each captured, status, output and results, retry and
cancel.
name: runs
- description: >-
Mutating repo configuration: runner, trail, public-sharing, and
gate-enforcement settings (requires repo manage_settings for every forge).
name: repo-settings
- description: The caller's open pull requests across their repositories.
name: pull-requests
- description: 'Service-authed only: editor-document sync behind the trail body editor.'
name: trails-internal
- description: The runner OIDC issuer's discovery document and JWKS. Machine-consumed.
name: runner-issuer
- name: repositories
x-group: Git
paths:
/repos/{repo_id}/changes/{number}/events:
get:
tags:
- trail-activity
summary: List or stream change events (repo_id addressing)
description: >-
Users Plugins
**Accepted credentials:** User token, Plugin installation token.
Returns trail events by opaque repo id with the same JSON cursor
pagination, category filters, open event catalog, Last-Event-ID SSE
resume, and from=head latest-push start as the name-addressed route.
Use an own-account bearer token (including supported service accounts)
or a Core-issued plugin installation bearer token, subject to the
permissions and restrictions below. Plugin assertion JWTs and plugin
OAuth user-delegation tokens are not accepted here.
Requires live repository pull permission (contents:read for plugin
installations). Other authorized automation principals can also use this
operation. Trails must be enabled. Send requests to the repository’s
primary API region. Streams recheck credentials, repository access and
placement.
operationId: changeEventsByRepoID
parameters:
- in: path
name: repo_id
required: true
schema:
type: string
- in: path
name: number
required: true
schema:
type: string
- description: Alias for type[eq]; repeatable or comma-separated.
explode: true
in: query
name: type
schema:
description: Alias for type[eq]; repeatable or comma-separated.
items:
type: string
type:
- array
- 'null'
- description: >-
Match runner, monitor, or finding categories; repeatable or
comma-separated.
explode: true
in: query
name: type[eq]
schema:
description: >-
Match runner, monitor, or finding categories; repeatable or
comma-separated.
items:
type: string
type:
- array
- 'null'
- description: >-
Exclude runner, monitor, or finding categories; repeatable or
comma-separated.
explode: true
in: query
name: type[ne]
schema:
description: >-
Exclude runner, monitor, or finding categories; repeatable or
comma-separated.
items:
type: string
type:
- array
- 'null'
- description: >-
Opaque JSON-page continuation. Filters may be omitted or repeated
with matching values.
explode: false
in: query
name: cursor
schema:
description: >-
Opaque JSON-page continuation. Filters may be omitted or repeated
with matching values.
type: string
- description: >-
JSON page size: default 200, capped at 1000; zero returns an empty
page.
explode: false
in: query
name: per_page
schema:
description: >-
JSON page size: default 200, capped at 1000; zero returns an empty
page.
type: string
- description: >-
Numeric resume cursor: for SSE, used when Last-Event-ID is absent;
for JSON pages, an alternative first-page start to cursor (mutually
exclusive with cursor).
explode: false
in: query
name: after
schema:
description: >-
Numeric resume cursor: for SSE, used when Last-Event-ID is absent;
for JSON pages, an alternative first-page start to cursor
(mutually exclusive with cursor).
type: string
- description: >-
head starts at the trail's latest push instead of the first event.
For SSE, Last-Event-ID and after take precedence, since they resume
a stream; the ready frame reports the start, head_sha and
latest_event_id. For JSON pages it starts the first page (empty when
the push has no events yet), is mutually exclusive with cursor and
after, and the body carries no start metadata: a trail with no head
pages the full log.
explode: false
in: query
name: from
schema:
description: >-
head starts at the trail's latest push instead of the first event.
For SSE, Last-Event-ID and after take precedence, since they
resume a stream; the ready frame reports the start, head_sha and
latest_event_id. For JSON pages it starts the first page (empty
when the push has no events yet), is mutually exclusive with
cursor and after, and the body carries no start metadata: a trail
with no head pages the full log.
enum:
- head
type: string
- description: text/event-stream streams events; otherwise returns a JSON page.
in: header
name: Accept
schema:
description: text/event-stream streams events; otherwise returns a JSON page.
type: string
- description: SSE numeric resume cursor; falls back to after.
in: header
name: Last-Event-ID
schema:
description: SSE numeric resume cursor; falls back to after.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewEventsResponseBody'
text/event-stream:
schema:
type: string
description: JSON event page or SSE stream
'400':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
description: Bad Request
'401':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
description: Unauthorized
'403':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
description: Forbidden
'404':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
description: Not Found
'422':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
description: Unprocessable Entity
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
description: Too Many Requests
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
description: Internal Server Error
'503':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
description: Service Unavailable
security:
- oauth2: []
- oidc: []
- bearerAuth: []
components:
schemas:
ReviewEventsResponseBody:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- /api/v1/schemas/ReviewEventsResponseBody.json
format: uri
readOnly: true
type: string
events:
items:
$ref: '#/components/schemas/ReviewEventJSON'
type:
- array
- 'null'
next_cursor:
type: string
required:
- events
type: object
ProblemDocument:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- /api/v1/schemas/ProblemDocument.json
format: uri
readOnly: true
type: string
code:
description: Stable error code; see https://entire.com/errors/.
type: string
detail:
description: Human-readable explanation; server errors omit internal details.
type: string
request_id:
description: Request identifier correlated with server logs.
minLength: 1
type: string
status:
description: HTTP response status.
format: int64
maximum: 599
minimum: 400
type: integer
title:
description: Short description of the HTTP error.
type: string
type:
description: Documentation URL for this error code.
format: uri
type: string
required:
- type
- title
- status
- detail
- code
- request_id
type: object
ReviewEventJSON:
additionalProperties: false
properties:
actor_id:
type:
- string
- 'null'
created_at:
format: date-time
type: string
event_type:
description: >-
Open event type. Periods separate domains; each segment uses
lowercase snake_case. Unknown future names must be tolerated.
type: string
x-open-enum:
- code_version.created
- review.started
- comment.created
- comment.updated
- comment.status_changed
- comment.stale_checked
- suggested_change.created
- gate.updated
- monitor.updated
- agent.updated
- runner.run
- runner.status
- runner.done
- runner.error
id:
type: string
payload: {}
review_id:
type:
- string
- 'null'
target_id:
type: string
target_type:
type: string
trail_id:
type: string
required:
- id
- trail_id
- review_id
- actor_id
- event_type
- target_type
- target_id
- payload
- created_at
type: object
securitySchemes:
bearerAuth:
bearerFormat: JWT
description: >-
Bearer token authorizing this operation's repository action. Each
operation's security requirement names the resource action the token
must be authorized for (pull or push).
scheme: bearer
type: http
oauth2:
description: OAuth 2.0 authorization code flow.
flows:
authorizationCode:
authorizationUrl: https://us.auth.entire.io/authorize
scopes:
offline_access: Stay signed in and receive a refresh token.
openid: Verify your identity.
tokenUrl: https://us.auth.entire.io/oauth/token
type: oauth2
oidc:
description: >-
OpenID Connect discovery document:
https://us.auth.entire.io/.well-known/openid-configuration
openIdConnectUrl: https://us.auth.entire.io/.well-known/openid-configuration
type: openIdConnect
````