API¶

OSCP messaging uses HTTPS with JSON payloads and token-based authentication. This section summarizes entry points, request/response rules, endpoints, and message payloads. Thick arrows in diagrams indicate OSCP messages; thin arrows indicate out-of-scope traffic. Detailed data types and validation rules live in data-models.md.

Entry Points & Examples¶

Base URL: exchanged during registration (e.g., https://host/oscp/fp/2.0).
Auth: bearer-style token per party, sent on every request.
Success: HTTP 204 with empty body; errors use HTTP status codes and optional JSON body.

Example request:

POST https://host/oscp/fp/2.0/handshake
Authorization: Token ABC123
Content-Type: application/json
X-Request-ID: 9c68e7b4-3c49-4c54-9ee0-123456789abc

{
  "required_behaviour": {
    "heartbeat_interval": 10,
    "measurement_configuration": ["CONTINUOUS"]
  }
}

Example error:

400 Bad Request
Content-Type: application/json
X-Request-ID: 9c68e7b4-3c49-4c54-9ee0-123456789abc

{ "message": "Unsupported heartbeat interval" }

General¶

Transport: HTTPS with Content-Type: application/json.
Authentication: token in Authorization header (no client certs; server certs required).

Required HTTP Headers¶

Header	Purpose	Mandatory
Authorization	Authentication token	Yes
X-Request-ID	Unique message ID	Yes
X-Correlation-ID	Links reply to corresponding request	Responses only
X-Segment-Index	Segment number in segmented message	Segmented messages only
X-Segment-Count	Total number of segments	Segmented messages only

Segmented Messages¶

Used when a message is too large for a single request.

Every segment MUST include X-Segment-Index and X-Segment-Count.
First segment: X-Segment-Index = 1; X-Correlation-ID refers to the original request (if any).
Subsequent segments: X-Correlation-ID refers to the first segment’s X-Request-ID.
Segments are concatenated in order of X-Segment-Index.

sequenceDiagram
    participant Sender
    participant Receiver

    Sender->>Receiver: Segment 1 (X-Request-ID:1001, X-Segment-Index:1/2, X-Correlation-ID:1000)
    Sender->>Receiver: Segment 2 (X-Request-ID:1002, X-Segment-Index:2/2, X-Correlation-ID:1001)
    Receiver->>Receiver: Reassemble in index order

HTTP Responses¶

Valid response: HTTP 204 No Content with no payload.
Error response: appropriate HTTP error code; may include body:

{
  "message": "Explanation of error"
}

X-Correlation-ID may be used in errors to reference the original request.

Rate Limits, Retries, Idempotency¶

Rate limits: agree per environment; if unspecified, default to client-side 10 req/s per endpoint with jitter.
Retries: use exponential backoff with cap; do not retry non-idempotent operations (registration changes) without operator confirmation.
Idempotency: carry X-Request-ID for uniqueness and X-Correlation-ID for responses/segments; receivers should treat identical X-Request-ID as the same request.

Endpoints¶

All endpoints extend the base URL exchanged during registration. Example: if base URL is https://host/oscp/fp/2.0, handshake is at https://host/oscp/fp/2.0/handshake. The Register endpoint is always <base>/register across OSCP versions.

Message	URL extension	Owners
Register	`<base>/register`	CP, FP, CO
Handshake	`<base>/handshake`	FP, CO
HandshakeAcknowledge	`<base>/handshake_acknowledge`	CP, FP
Heartbeat	`<base>/heartbeat`	CP, FP, CO
UpdateGroupCapacityForecast	`<base>/update_group_capacity_forecast`	FP, CO
AdjustGroupCapacityForecast	`<base>/adjust_group_capacity_forecast`	CP
GroupCapacityComplianceError	`<base>/group_capacity_compliance_error`	CP
UpdateGroupMeasurements	`<base>/update_group_measurements`	CP
UpdateAssetMeasurements	`<base>/update_asset_measurements`	CO

Connection¶

Registration¶

Enables token-based authentication per endpoint.

Endpoint	Method	Direction
`/oscp/fp/2.0/register`	POST, PUT, DELETE	CP → FP or CO → FP
`/oscp/cp/2.0/register`	POST, PUT, DELETE	FP → CP
`/oscp/co/2.0/register`	POST, PUT, DELETE	FP → CO

Field	Type	Card.	Description
token	string	1..1	Token for other party to authenticate
version_url	VersionURL	1..*	OSCP version + base URL

VersionURL example:

{
  "version": "2.0",
  "base_url": "https://example.com/oscp/cp/2.0"
}

Behavior: POST initiates registration; PUT switches endpoint; DELETE unregisters and stops communication.

Handshake¶

Initializes communication preferences (e.g., heartbeat interval).

Endpoint	Method	Direction
`/oscp/fp/2.0/handshake`	POST	CP → FP
`/oscp/co/2.0/handshake`	POST	FP → CO

Field	Type	Description
required_behaviour	RequiredBehaviour	Optional overall field; when present, must include `measurement_configuration` (per schema) and may include `heartbeat_interval`

HandshakeAcknowledge¶

Response to a Handshake; payload matches Handshake.

Endpoint	Method	Direction
`/oscp/cp/2.0/handshake_acknowledge`	POST	FP → CP
`/oscp/fp/2.0/handshake_acknowledge`	POST	CO → FP

Heartbeat¶

Ensures the connection is alive.

Endpoint	Method	Direction
`/oscp/fp/2.0/heartbeat`	POST	CP → FP, CO → FP
`/oscp/cp/2.0/heartbeat`	POST	FP → CP
`/oscp/co/2.0/heartbeat`	POST	FP → CO

Field	Type	Card.	Description
offline_mode_at	datetime	1..1	Time after which peer assumes sender is offline

sequenceDiagram
    participant Sender
    participant Receiver

    Sender->>Receiver: Heartbeat(offline_mode_at = t1)
    Receiver-->>Sender: HTTP 204
    Sender->>Receiver: Heartbeat(offline_mode_at = t2)
    Receiver-->>Sender: HTTP 204
    Sender--X Receiver: Missed heartbeat -> offline after t2

Capacity Messages¶

UpdateGroupCapacityForecast¶

Sent by CP to FP, or FP to CO.

Endpoint	Method	Direction
`/oscp/fp/2.0/update_group_capacity_forecast`	POST	CP → FP
`/oscp/co/2.0/update_group_capacity_forecast`	POST	FP → CO

Field	Type	Card.	Description
group_id	string	1..1	Identifier of the group
type	CapacityForecastType	1..1	Type of forecast (`CONSUMPTION`, `GENERATION`, `FALLBACK_CONSUMPTION`, `FALLBACK_GENERATION`, `OPTIMUM`)
forecasted_blocks	ForecastedBlock[]	1..*	Capacity blocks

AdjustGroupCapacityForecast¶

FP requests temporary additional capacity.

Endpoint	Method	Direction
`/oscp/cp/2.0/adjust_group_capacity_forecast`	POST	FP → CP

Payload structure matches UpdateGroupCapacityForecast.

GroupCapacityComplianceError¶

Sent when FP cannot comply with received capacity.

Endpoint	Method	Direction
`/oscp/cp/2.0/group_capacity_compliance_error`	POST	FP → CP

Field	Type	Card.	Description
message	string	1..1	Description of non-compliance
forecasted_blocks	ForecastedBlock[]	0..*	Optional list of violating blocks

Metering Messages¶

UpdateGroupMeasurements¶

Aggregated energy usage from FP to CP.

Endpoint	Method	Direction
`/oscp/cp/2.0/update_group_measurements`	POST	FP → CP

Field	Type	Card.	Description
group_id	string	1..1	Group identifier
measurements	EnergyMeasurement[]	1..*	Accumulated group measurements

UpdateAssetMeasurements¶

Per-resource measurements from FP to CO.

Endpoint	Method	Direction
`/oscp/co/2.0/update_asset_measurements`	POST	FP → CO

Field	Type	Card.	Description
group_id	string	1..1	Group identifier
measurements	AssetMeasurement[]	1..*	Asset-level measurements (schema references `asset-measurement.json` for items)