Skip to content

Batch Event Ingest API Contract

Who is this for (1)

Contract: Batch Event Ingest API

Feature: 039-cli-2x-readiness Version: 2.0.0 Date: 2026-02-12 Branch: 2.x Purpose: Enable the SaaS team to validate their batch endpoint against CLI payloads without consulting CLI source code.


Table of Contents

  1. Authentication Flow
  2. Event Envelope Field Reference
  3. Batch Request/Response Format
  4. Event Types and Payload Schemas
  5. Lane Vocabulary (Canonical 7-Lane)
  6. Error Categorization
  7. Fixture Data
  8. Tracker Snapshot Publish Payload (Feature 048)

1. Authentication Flow

The CLI uses a JWT-based authentication flow with credential persistence.

1.1 Login (Obtain Tokens)

POST /api/v1/token/
Content-Type: application/json
{
"username": "[email protected]",
"password": "s3cret"
}

Success Response (HTTP 200):

{
"access": "<jwt_access_token>",
"refresh": "<jwt_refresh_token>",
"access_lifetime": 900,
"refresh_lifetime": 604800,
"team_slug": "my-team"
}
Response FieldTypeRequiredDescription
accessstringYesJWT access token
refreshstringYesJWT refresh token
access_lifetimeintegerNoAccess token lifetime in seconds (default: 900 = 15 min)
refresh_lifetimeintegerNoRefresh token lifetime in seconds (default: 604800 = 7 days)
team_slugstringNoTeam identifier for the authenticated user

Error Response (HTTP 401):

{
"error": "Invalid username or password"
}

1.2 Token Refresh

POST /api/v1/token/refresh/
Content-Type: application/json
{
"refresh": "<jwt_refresh_token>"
}

Success Response (HTTP 200):

{
"access": "<new_jwt_access_token>",
"refresh": "<new_jwt_refresh_token>",
"access_lifetime": 900,
"refresh_lifetime": 604800,
"team_slug": "my-team"
}

Error Response (HTTP 401): The CLI clears stored credentials and prompts the user to re-authenticate.

1.3 Authorization Header

All authenticated requests (including batch ingest) include:

Authorization: Bearer <jwt_access_token>

1.4 Automatic Token Refresh Behavior

The CLI checks the access token expiry before each request:

  1. If the access token is valid, use it directly.
  2. If the access token is expired but the refresh token is valid, silently refresh via /api/v1/token/refresh/.
  3. If the refresh also fails (401), clear credentials and return None (caller handles re-auth prompting).

1.5 Credential Storage

Credentials are stored on the user’s machine at ~/.spec-kitty/credentials in TOML format with chmod 600 permissions.

[tokens]
access = "<jwt_access_token>"
refresh = "<jwt_refresh_token>"
access_expires_at = "2026-02-12T10:15:00"
refresh_expires_at = "2026-02-19T10:00:00"
[user]
username = "[email protected]"
team_slug = "my-team"
[server]
url = "https://team.spec-kitty.ai"

A file lock (~/.spec-kitty/credentials.lock) prevents concurrent access.


2. Event Envelope Field Reference

This historical batch-endpoint contract describes the retired sync transport. The external spec-kitty-events package’s Pydantic Event model remains the schema reference; src/specify_cli/sync/emitter.py was deleted with that transport and is not a live CLI source.

2.1 Core Fields (Pydantic Event model)

FieldTypeRequiredConstraintsExample
event_idstringYesExactly 26 chars, ULID format (Crockford Base32: [0-9A-HJKMNP-TV-Z]{26})"01JMBY1234567890ABCDEFGH"
event_typestringYesOne of the 8 known types (see Section 4)"WPStatusChanged"
aggregate_idstringYesMin 1 char. Entity this event modifies."WP01" or "039-cli-2x-readiness"
payloadobjectYesEvent-specific data (see Section 4 for per-type schemas){"wp_id": "WP01", ...}
timestampstringYesISO 8601 with timezone (wall-clock, not used for ordering)"2026-02-12T10:00:00+00:00"
node_idstringYesMin 1 char. Stable machine identifier (12-char hex)"a1b2c3d4e5f6"
lamport_clockintegerYes>= 0, monotonically increasing per node42
causation_idstringNo26 chars ULID if present, null for root events"01JMBY1234567890ABCDEFGI"

2.2 Extended Fields (Added by EventEmitter)

These fields are added by the CLI’s EventEmitter._emit() method and are present on every event in the batch payload:

FieldTypeRequiredConstraintsExample
aggregate_typestringYesOne of: "WorkPackage", "Feature""WorkPackage"
team_slugstringYesNon-empty string. "local" if team unavailable."my-team"
project_uuidstringYes*UUID v4 format (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx). If missing, event is queued locally only and never sent to batch endpoint."550e8400-e29b-41d4-a716-446655440000"
project_slugstringNoKebab-case project name, may be null"spec-kitty"
git_branchstringNoCurrent git branch, may be null"039-cli-2x-readiness-WP07"
head_commit_shastringNoFull 40-char SHA, may be null"0cf3f906f4f979a000cf04c78688a397d69b6a37"
repo_slugstringNoowner/repo format, may be null"priivacy/spec-kitty"

*project_uuid is required for events to reach the batch endpoint. Events without project_uuid are queued locally but never transmitted.

2.3 ULID Format Specification

Both event_id and causation_id use ULID (Universally Unique Lexicographically Sortable Identifier):

  • Length: exactly 26 characters
  • Encoding: Crockford Base32 (0123456789ABCDEFGHJKMNPQRSTVWXYZ)
  • Structure: 10-char timestamp (48-bit millisecond epoch) + 16-char randomness (80-bit)
  • Regex: ^[0-9A-HJKMNP-TV-Z]{26}$
  • ULIDs are sortable by creation time when compared lexicographically

2.4 UUID v4 Format

The project_uuid field uses UUID v4 (random):

  • Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx where y is one of [89ab]
  • Example: "550e8400-e29b-41d4-a716-446655440000"

3. Batch Request/Response Format

3.1 Batch Request

POST /api/v1/events/batch/
Authorization: Bearer <jwt_access_token>
Content-Type: application/json
Content-Encoding: gzip

Body (before gzip compression):

{
"events": [
{ ... event 1 ... },
{ ... event 2 ... }
]
}
ParameterValue
URLPOST {server_url}/api/v1/events/batch/ (trailing slash required)
Max batch size1000 events
CompressionBody is gzip-compressed (Content-Encoding: gzip)
OrderingEvents are drained from the offline queue in FIFO order: timestamp ASC, id ASC
Timeout60 seconds

The CLI constructs the payload as follows (from batch.py):

payload = json.dumps({"events": events}).encode("utf-8")
compressed = gzip.compress(payload)

3.2 Success Response (HTTP 200)

{
"results": [
{"event_id": "01JMBY1234567890ABCDEFGH", "status": "success"},
{"event_id": "01JMBY1234567890ABCDEFGI", "status": "duplicate"},
{"event_id": "01JMBY1234567890ABCDEFGJ", "status": "rejected", "error": "Invalid payload: missing field 'wp_id'"}
]
}

Per-event status values:

StatusMeaningCLI Behavior
successEvent accepted and storedRemove from offline queue
duplicateEvent with this event_id already existsRemove from offline queue (treated as success)
rejectedEvent failed server-side validationRetain in queue, increment retry_count

Event journal extension (#2124/#2131): the CLI behavior above describes the current destructive offline event queue. After event-sync-retention-delivery-01KVYWRG lands, event payload rows MUST NOT be deleted on success or duplicate; those outcomes update the delivery ledger for the resolved target. This extension applies to event payload delivery only. body_upload_queue / body_upload_failure_log remain separate non-event queue surfaces and are not converted into event-journal rows by that mission.

Additive note (event-sync-retention-delivery-01KVYWRG, #2124/#2146 — strictly additive, NFR-006/C-006). The wire protocol in this section is unchanged: the request body, the per-event status vocabulary (success / duplicate / rejected), and every fixture below stay exactly as specified. What changes is only the local CLI behavior for event payload rows while the (since-retired) local receiver drove delivery (the canonical source of this mapping was src/specify_cli/delivery/receivers.py, removed with the delivery subsystem on this line — spec-kitty#5 / PR #114; the table is retained as historical wire-contract documentation):

Per-event / batch outcomeLocal event-row effect after this mission
successDelivery ledger UPDATE for the resolved target (records delivered); the local event-journal row is retained, never deleted.
duplicateSame as success — ledger UPDATE, row retained (idempotent re-delivery, NFR-003).
rejectedLedger rejection state for the target; payload retained and inspectable; eligible for a later attempt.
oversized / permanent per-event failureLedger terminal-failed state; excluded from future automatic selection but never deleted (FR-015).
batch-level transient failure (401 / 403 / 408 / 429 / 5xx / timeout)Updates attempt metadata only (no per-event content verdict); never poisons per-event retry counts.

Row deletion now happens only via explicit sync gc / sync archive, which preserve delivery history/provenance. This extension covers event payload delivery only. body_upload_queue and body_upload_failure_log remain owned by sync/queue.py, are not event-journal rows, and no status field in this contract may imply otherwise (event-sync-delivery contract §6).

Per-event result fields:

FieldTypePresent WhenDescription
event_idstringAlwaysThe ULID of the event this result refers to
statusstringAlwaysOne of: "success", "duplicate", "rejected"
errorstringstatus == "rejected"Human-readable validation failure reason
error_messagestringstatus == "rejected"Alternative field name (CLI checks both error_message and error)

Note: The CLI accepts both error_message and error fields for the rejection reason. The SaaS should provide at least one.

3.3 Validation Error Response (HTTP 400)

{
"error": "Batch processing failed",
"details": "Transaction rolled back: 3 events failed schema validation"
}
FieldTypeRequiredDescription
errorstringYesTop-level error message
detailsstring or listYesPer-event failure reasons. Can be a JSON string containing a list, a JSON list directly, or a plain description string.

Structured details format (preferred — enables per-event error categorization):

{
"error": "Batch processing failed",
"details": [
{"event_id": "01JMBY...", "error": "Missing required field: wp_id"},
{"event_id": "01JMBY...", "reason": "Invalid event_type: FooBar"}
]
}

The CLI parses details as follows:

  1. If details is a list: treat each item as {"event_id": ..., "error"|"reason": ...}
  2. If details is a JSON string encoding a list: parse and treat as above
  3. If details is a plain string: apply the top-level error to all events in the batch

3.4 Authentication Error Response (HTTP 401)

{
"error": "Token expired or invalid"
}

CLI behavior: Prints “Batch sync failed: Authentication failed (401)”, marks all events as rejected with error_category: "auth_expired", and increments retry count.

3.5 Permission Error Response (HTTP 403)

{
"error": "Insufficient permissions for team 'my-team' on project 'my-project'"
}

3.6 Server Error Responses (HTTP 5xx)

Any non-200/400/401 status code is treated as a server error. All events are marked rejected with error_category: "server_error".


4. Event Types and Payload Schemas

The retired CLI transport emitted 8 event types. Its _PAYLOAD_RULES implementation was deleted with src/specify_cli/sync/emitter.py; this section is retained as wire-contract history.

4.1 WPStatusChanged

Emitted when a work package changes lane (status).

aggregate_typeaggregate_id format
WorkPackage"WP01" (the wp_id)

Payload fields:

FieldTypeRequiredConstraintsExample
wp_idstringYesPattern: ^WP\d{2}$"WP01"
from_lanestringYesOne of the 7 canonical lanes (see below)"planned"
to_lanestringYesOne of the 7 canonical lanes (see below)"in_progress"
actorstringNoString if present (actor identity)"claude-agent"
feature_slugstringNoNullable string"039-cli-2x-readiness"

Canonical 7-lane vocabulary (accepted values for from_lane and to_lane): planned, claimed, in_progress, for_review, done, blocked, canceled

Lane values are passed through directly from the canonical status model — no collapse or mapping is applied.

4.2 WPCreated

Emitted when a new work package is created.

aggregate_typeaggregate_id format
WorkPackage"WP01" (the wp_id)

Payload fields:

FieldTypeRequiredConstraintsExample
wp_idstringYesPattern: ^WP\d{2}$"WP03"
titlestringYesMin 1 char"Implement batch sync"
feature_slugstringYesMin 1 char"039-cli-2x-readiness"
dependencieslist[string]NoEach item matches ^WP\d{2}$["WP01", "WP02"]

4.3 WPAssigned

Emitted when a work package is assigned to an agent.

aggregate_typeaggregate_id format
WorkPackage"WP01" (the wp_id)

Payload fields:

FieldTypeRequiredConstraintsExample
wp_idstringYesPattern: ^WP\d{2}$"WP07"
agent_idstringYesMin 1 char"wp07-agent"
phasestringYesOne of: "implementation", "review""implementation"
retry_countintegerNo>= 00

4.4 FeatureCreated

Emitted when a new feature is created.

aggregate_typeaggregate_id format
Feature"039-cli-2x-readiness" (feature_slug)

Payload fields:

FieldTypeRequiredConstraintsExample
feature_slugstringYesPattern: ^\d{3}-[a-z0-9-]+$"039-cli-2x-readiness"
feature_numberstringYesPattern: ^\d{3}$"039"
target_branchstringYesMin 1 char"main"
wp_countintegerYes>= 09
created_atstringNoISO 8601 datetime string"2026-02-12T10:00:00+00:00"

4.5 FeatureCompleted

Emitted when all work packages in a feature reach terminal state.

aggregate_typeaggregate_id format
Feature"039-cli-2x-readiness" (feature_slug)

Payload fields:

FieldTypeRequiredConstraintsExample
feature_slugstringYesMin 1 char"039-cli-2x-readiness"
total_wpsintegerYes>= 09
completed_atstringNoISO 8601 datetime string"2026-02-12T18:00:00+00:00"
total_durationstringNoNullable string"8h 30m"

4.6 HistoryAdded

Emitted when a history entry is added to a work package.

aggregate_typeaggregate_id format
WorkPackage"WP01" (the wp_id)

Payload fields:

FieldTypeRequiredConstraintsExample
wp_idstringYesPattern: ^WP\d{2}$"WP07"
entry_typestringYesOne of: "note", "review", "error", "comment""note"
entry_contentstringYesMin 1 char"Completed contract document"
authorstringNoString if present"wp07-agent"

4.7 ErrorLogged

Emitted when an error is logged during workflow execution.

aggregate_typeaggregate_id format
WorkPackage (if wp_id present) or Feature"WP01" or "error"

Payload fields:

FieldTypeRequiredConstraintsExample
error_typestringYesOne of: "validation", "runtime", "network", "auth", "unknown""validation"
error_messagestringYesMin 1 char"Missing required field: wp_id"
wp_idstringNoNullable string"WP03"
stack_tracestringNoNullable string"Traceback ..."
agent_idstringNoNullable string"wp07-agent"

4.8 DependencyResolved

Emitted when a work package dependency is resolved.

aggregate_typeaggregate_id format
WorkPackage"WP04" (the dependent wp_id)

Payload fields:

FieldTypeRequiredConstraintsExample
wp_idstringYesPattern: ^WP\d{2}$"WP04"
dependency_wp_idstringYesPattern: ^WP\d{2}$"WP02"
resolution_typestringYesOne of: "completed", "skipped", "merged""completed"

5. Lane Vocabulary (Canonical 7-Lane)

The CLI emits WPStatusChanged events using the full canonical 7-lane vocabulary directly. No lane collapse or mapping is applied — _SYNC_LANE_MAP has been removed.

5.1 Canonical Lanes

LaneDescription
plannedWork not yet started
claimedClaimed by an agent but not yet in progress
in_progressActive work underway
for_reviewSubmitted for review
doneComplete (terminal)
blockedBlocked by dependency or issue
canceledCanceled (terminal)

All 7 values are valid for both from_lane and to_lane in WPStatusChanged payloads.

5.2 SaaS Acceptance Requirements

The SaaS batch endpoint MUST accept all 7 canonical lane values in WPStatusChanged payload fields from_lane and to_lane.

Unknown lane values MUST be rejected with a descriptive error.

5.3 Alias Resolution (CLI-Side Only)

The CLI resolves the user-facing alias doing to in_progress at input boundaries (e.g., move-task --to doing). This resolution happens before event emission — the alias doing never appears in emitted events.


6. Error Categorization

The retired CLI transport categorized batch errors using keyword matching. Its src/specify_cli/sync/batch.py implementation was deleted; these categories remain historical wire-contract documentation.

6.1 Categories

CategoryKeywordsCLI Action Suggestion
schema_mismatchinvalid, schema, field, missing, typeInspect the invalid event with --report <file.json>
auth_expiredtoken, expired, unauthorized, 401Run 'spec-kitty auth login' to refresh credentials
server_errorinternal, 500, timeout, unavailableRetry later or check server status
unknown(no keywords match)Inspect the failure report for details: --report <file.json>

The CLI applies categorize_error() to the error string from each rejected event result or the top-level error message from HTTP 400 responses.

6.2 Failure Report Format

The CLI can generate a JSON failure report after batch sync:

{
"generated_at": "2026-02-12T10:00:00+00:00",
"summary": {
"total_events": 100,
"synced": 90,
"duplicates": 3,
"failed": 7,
"categories": {
"schema_mismatch": 5,
"auth_expired": 1,
"unknown": 1
}
},
"failures": [
{
"event_id": "01JMBY1234567890ABCDEFGH",
"error": "Missing required field: wp_id",
"category": "schema_mismatch"
}
]
}

7. Fixture Data

The following fixtures are complete request/response examples. Each fixture can be used as-is for integration testing. The JSON is shown uncompressed for readability; in production the request body is gzip-compressed.

All fixture event data validates against the Pydantic Event model. See tests/contract/test_handoff_fixtures.py for the automated contract test.

Fixture 1: Single WPStatusChanged (Happy Path)

Request Body:

{
"events": [
{
"event_id": "01JMBY7K8N3QRVX2DPFG5HWT4E",
"event_type": "WPStatusChanged",
"aggregate_id": "WP01",
"aggregate_type": "WorkPackage",
"payload": {
"wp_id": "WP01",
"from_lane": "planned",
"to_lane": "in_progress",
"actor": "claude-agent",
"feature_slug": "039-cli-2x-readiness"
},
"timestamp": "2026-02-12T10:00:00+00:00",
"node_id": "a1b2c3d4e5f6",
"lamport_clock": 1,
"causation_id": null,
"team_slug": "priivacy",
"project_uuid": "550e8400-e29b-41d4-a716-446655440000",
"project_slug": "spec-kitty",
"git_branch": "039-cli-2x-readiness-WP01",
"head_commit_sha": "0cf3f906f4f979a000cf04c78688a397d69b6a37",
"repo_slug": "priivacy/spec-kitty"
}
]
}

Expected Response (HTTP 200):

{
"results": [
{
"event_id": "01JMBY7K8N3QRVX2DPFG5HWT4E",
"status": "success"
}
]
}

Key fields to verify: event_id is 26-char ULID, from_lane and to_lane are canonical 7-lane values, project_uuid is valid UUID v4.


Fixture 2: Mixed Batch (3 Event Types)

Request Body:

{
"events": [
{
"event_id": "01JMBYA1B2C3D4E5F6G7H8J9KA",
"event_type": "WPStatusChanged",
"aggregate_id": "WP02",
"aggregate_type": "WorkPackage",
"payload": {
"wp_id": "WP02",
"from_lane": "in_progress",
"to_lane": "for_review",
"actor": "wp02-agent",
"feature_slug": "039-cli-2x-readiness"
},
"timestamp": "2026-02-12T11:00:00+00:00",
"node_id": "a1b2c3d4e5f6",
"lamport_clock": 10,
"causation_id": null,
"team_slug": "priivacy",
"project_uuid": "550e8400-e29b-41d4-a716-446655440000",
"project_slug": "spec-kitty",
"git_branch": "039-cli-2x-readiness-WP02",
"head_commit_sha": "1af4b906f4f979a000cf04c78688a397d69b6a38",
"repo_slug": "priivacy/spec-kitty"
},
{
"event_id": "01JMBYA1B2C3D4E5F6G7H8J9KB",
"event_type": "WPCreated",
"aggregate_id": "WP10",
"aggregate_type": "WorkPackage",
"payload": {
"wp_id": "WP10",
"title": "End-to-end integration test suite",
"feature_slug": "039-cli-2x-readiness",
"dependencies": ["WP02", "WP03"]
},
"timestamp": "2026-02-12T11:01:00+00:00",
"node_id": "a1b2c3d4e5f6",
"lamport_clock": 11,
"causation_id": null,
"team_slug": "priivacy",
"project_uuid": "550e8400-e29b-41d4-a716-446655440000",
"project_slug": "spec-kitty",
"git_branch": "main",
"head_commit_sha": "2bf5c917f5f989b111df15d89799b498e7ac7b49",
"repo_slug": "priivacy/spec-kitty"
},
{
"event_id": "01JMBYA1B2C3D4E5F6G7H8J9KC",
"event_type": "FeatureCreated",
"aggregate_id": "040-next-feature",
"aggregate_type": "Feature",
"payload": {
"feature_slug": "040-next-feature",
"feature_number": "040",
"target_branch": "main",
"wp_count": 5,
"created_at": "2026-02-12T11:02:00+00:00"
},
"timestamp": "2026-02-12T11:02:00+00:00",
"node_id": "a1b2c3d4e5f6",
"lamport_clock": 12,
"causation_id": null,
"team_slug": "priivacy",
"project_uuid": "550e8400-e29b-41d4-a716-446655440000",
"project_slug": "spec-kitty",
"git_branch": "main",
"head_commit_sha": "2bf5c917f5f989b111df15d89799b498e7ac7b49",
"repo_slug": "priivacy/spec-kitty"
}
]
}

Expected Response (HTTP 200):

{
"results": [
{"event_id": "01JMBYA1B2C3D4E5F6G7H8J9KA", "status": "success"},
{"event_id": "01JMBYA1B2C3D4E5F6G7H8J9KB", "status": "success"},
{"event_id": "01JMBYA1B2C3D4E5F6G7H8J9KC", "status": "success"}
]
}

Key fields to verify: Three different event types in one batch, dependencies is an array of WP IDs, feature_number matches the pattern ^\d{3}$.


Fixture 3: Duplicate Event

Request Body (same event_id as Fixture 1, sent a second time):

{
"events": [
{
"event_id": "01JMBY7K8N3QRVX2DPFG5HWT4E",
"event_type": "WPStatusChanged",
"aggregate_id": "WP01",
"aggregate_type": "WorkPackage",
"payload": {
"wp_id": "WP01",
"from_lane": "planned",
"to_lane": "in_progress",
"actor": "claude-agent",
"feature_slug": "039-cli-2x-readiness"
},
"timestamp": "2026-02-12T10:00:00+00:00",
"node_id": "a1b2c3d4e5f6",
"lamport_clock": 1,
"causation_id": null,
"team_slug": "priivacy",
"project_uuid": "550e8400-e29b-41d4-a716-446655440000",
"project_slug": "spec-kitty",
"git_branch": "039-cli-2x-readiness-WP01",
"head_commit_sha": "0cf3f906f4f979a000cf04c78688a397d69b6a37",
"repo_slug": "priivacy/spec-kitty"
}
]
}

Expected Response (HTTP 200):

{
"results": [
{
"event_id": "01JMBY7K8N3QRVX2DPFG5HWT4E",
"status": "duplicate"
}
]
}

Key point: The SaaS MUST detect the duplicate by event_id and return "duplicate" status (not an error). The CLI treats duplicates as successful — the event is removed from the offline queue.


Fixture 4: Rejected Event (Missing Required Field)

Request Body (missing error_type in ErrorLogged payload):

{
"events": [
{
"event_id": "01JMBYB3C4D5E6F7G8H9J0KABM",
"event_type": "ErrorLogged",
"aggregate_id": "error",
"aggregate_type": "Feature",
"payload": {
"error_message": "Something went wrong"
},
"timestamp": "2026-02-12T12:00:00+00:00",
"node_id": "a1b2c3d4e5f6",
"lamport_clock": 20,
"causation_id": null,
"team_slug": "priivacy",
"project_uuid": "550e8400-e29b-41d4-a716-446655440000",
"project_slug": "spec-kitty",
"git_branch": "main",
"head_commit_sha": null,
"repo_slug": "priivacy/spec-kitty"
}
]
}

Expected Response (HTTP 200 with per-event rejection):

{
"results": [
{
"event_id": "01JMBYB3C4D5E6F7G8H9J0KABM",
"status": "rejected",
"error": "Invalid payload for ErrorLogged: missing required field 'error_type'"
}
]
}

Key point: The SaaS should validate payloads per event type and return "rejected" with a descriptive error message. The error should contain keywords like missing or field so the CLI categorizes it as schema_mismatch.


Fixture 5: HTTP 400 Error Response

Request Body (entire batch fails validation):

{
"events": [
{
"event_id": "01JMBYC4D5E6F7G8H9J0K1WABN",
"event_type": "WPStatusChanged",
"aggregate_id": "WP01",
"aggregate_type": "WorkPackage",
"payload": {
"wp_id": "WP01",
"from_lane": "planned",
"to_lane": "in_progress",
"actor": "agent",
"feature_slug": null
},
"timestamp": "2026-02-12T13:00:00+00:00",
"node_id": "a1b2c3d4e5f6",
"lamport_clock": 30,
"causation_id": null,
"team_slug": "priivacy",
"project_uuid": "550e8400-e29b-41d4-a716-446655440000",
"project_slug": "spec-kitty",
"git_branch": null,
"head_commit_sha": null,
"repo_slug": null
}
]
}

Expected Response (HTTP 400):

{
"error": "Batch validation failed",
"details": [
{
"event_id": "01JMBYC4D5E6F7G8H9J0K1WABN",
"error": "Invalid schema: project_uuid authorization check failed for team 'priivacy'"
}
]
}

Key point: The details field MUST be present for HTTP 400 responses. The CLI depends on it for per-event diagnostics. When details is a structured list, the CLI can categorize each failure independently.


8. Tracker Snapshot Publish Payload (Feature 048)

Historical. The CLI no longer publishes tracker snapshots: sync_publish refuses for both SaaS-backed and local tracker providers (src/specify_cli/tracker/saas_service.py, src/specify_cli/tracker/local_service.py, #3168), so this repository produces no snapshot payload for the SaaS to validate. The endpoint contract is owned upstream (spec-kitty/saas). The payload the CLI used to send, with its routing fields, null semantics and idempotency key, is recorded in tracker-snapshot-publish.md.


Appendix A: Full Event Lifecycle

1. CLI action triggers event emission (e.g., `spec-kitty agent tasks move-task WP01 --to doing`)
2. EventEmitter._emit() builds event dict with all envelope + extended fields
3. EventEmitter._validate_event() validates:
a. Pydantic Event model (core envelope fields)
b. aggregate_type is valid
c. event_type is one of 8 known types
d. ULID patterns for event_id and causation_id
e. Payload fields match per-event-type rules
4. If project_uuid is missing: queue locally only (no batch send)
5. If authenticated + WebSocket connected: send via WebSocket
6. Otherwise: queue to SQLite offline queue (~/.spec-kitty/queue.db)
7. On the retired background flush:
a. drain_queue(limit=1000) retrieves events FIFO
b. Gzip compress and POST to /api/v1/events/batch/
c. Parse per-event results
d. Remove success/duplicate events from queue
e. Increment retry_count for rejected events

Appendix B: Source File Reference

ComponentFile / source
Pydantic Event modelExternal spec-kitty-events dependency, pinned at c93dbfbf5243330349452a31d05bca2ece26ceea (pyproject.toml)
Retired sync transportDeleted with issue #5; this appendix is historical only
Status fan-out (canonical 7-lane)src/specify_cli/status/emit.py (_status_fan_out)
Retired public event APIDeleted with issue #5