API data types
Look up exact connection, grant, resource, mapping, external record, event, and delivery fields used by the Connector API.
Connector uses the following request and response objects. Fields marked required must be present; omission of an optional request field follows its listed default or the operation's replacement and PATCH rules.
The OpenAPI contract contains nested schemas
and validation constraints. Unknown input fields and invalid types reject the
request. A nullable response field is explicitly marked with null.
Endpoint object
The Endpoint object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
side | string | Yes | Stable side within this connection. Values: a, b. |
product | string | Yes | Participating product or custom registration. Values: infra, guard, custom. |
organization_id | string | Yes | Product organization; must belong to the owning Solarius organization. |
installation_id | string | No | Required for Infra or Guard; rejected for a custom endpoint. |
integration_id | string | No | Required for custom; rejected for Infra or Guard. |
Native sides require installation_id and reject integration_id. Custom sides require integration_id and reject installation_id. Both belong to the owning Solarius organization.
ConnectionCreate object
The ConnectionCreate object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
name | string | Yes | Display name; renaming preserves identity. |
endpoints | Endpoint[] | Yes | Exactly one a endpoint and one b endpoint; identities are immutable. |
Connection object
The Connection object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | Yes | Connection identity. |
name | string | Yes | Display name. |
revision | integer | Yes | Configuration revision. |
state | string | Yes | Configuration and observed health. Values: draft, pending_approval, connecting, connected, degraded, disconnected, paused, revoked. |
active_grant_revision | integer | Yes | Combined active grant generation; 0 before initial activation. |
endpoints | Endpoint[] | Yes | Immutable participant identities. |
last_synchronized_at | string or null | Yes | Last complete synchronization; null before success. |
GrantCreate object
The GrantCreate object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
source | string | Yes | Source endpoint side. Values: a, b. |
destination | string | Yes | Other endpoint side; must differ from source. Values: a, b. |
source_scope_ids | string[] | Yes | Explicit source projects, groups, or custom integration ID; no wildcard. |
destination_scope_id | string | Yes | Receiving project, asset group, or integration ID. |
categories | string[] | Yes | Nonempty categories supported by this direction. |
label_keys | string[] | No | Inventory labels permitted to cross the boundary; omitted shares no labels. Default: []. |
Grant object
The Grant object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | Yes | Grant identity. |
revision | integer | Yes | Immutable reviewed revision. |
state | string | Yes | Approval and activation state. Values: pending_approval, approved, active, rejected, superseded, revoked. |
selection | GrantCreate | Yes | Structure defined by the GrantCreate schema. |
approved_sides | string[] | Yes | Sides that approved this exact selection. |
Reason object
The Reason object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
reason | string | Yes | Audited reason; empty values are rejected. |
GrantDecision object
The GrantDecision object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
side | string | Yes | Side for which the caller has approval authority. Values: a, b. |
decision | string | Yes | Approve or reject the reviewed revision. Values: approve, reject. |
reason | string | Yes | Audited explanation. |
Resource object
The Resource object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
resource_key | string | Yes | Opaque qualified identity; never construct this value from a name. |
product | string | Yes | Source product. Values: infra, guard, custom. |
organization_id | string | Yes | Source product organization. |
installation_id | string or null | Yes | Source installation; null for custom records. |
resource_type | string | Yes | Native resource type, or service, deployment, or ticket for custom records. |
resource_id | string | Yes | Native ID or integration-scoped external ID. |
source_revision | integer or null | Yes | Monotonic source revision; null when the source has no revision. |
observed_at | string | Yes | Time of the source observation. |
received_at | string | Yes | Time Connector received the record. |
summary | object | Yes | Structure defined by the object schema. |
The summary contains required name and optional state, url, approved labels, and severity. Only the source grant categories determine which optional fields are visible. Null source revision cannot support numeric revision comparison; read present state before a dependent change.
MappingCreate object
The MappingCreate object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
source_resource_key | string | Yes | Qualified identity on one connection endpoint. |
destination_resource_key | string | Yes | Qualified identity on the other endpoint. |
reason | string | Yes | Why these records represent the same workload. |
Mapping object
The Mapping object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | Yes | Mapping identity. |
revision | integer | Yes | Mapping revision. |
source_resource_key | string | Yes | Confirmed source identity. |
destination_resource_key | string | Yes | Confirmed destination identity. |
state | string | Yes | Whether both referenced resources remain visible. Values: active, stale. |
reason | string | Yes | Audited association reason. |
IntegrationCreate object
The IntegrationCreate object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
name | string | Yes | Integration display name. |
description | string | No | Purpose of this integration. Default: "". |
homepage_url | string | Yes | HTTPS location of the integration owner or application. |
owner_team_id | string | Yes | Responsible team in the owning Solarius organization. |
Integration object
The Integration object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | Yes | Registered integration identity. |
name | string | Yes | Display name. |
description | string | Yes | Purpose. |
homepage_url | string | Yes | Application HTTPS URL. |
enabled | boolean | Yes | Whether the integration can exchange records. |
revision | integer | Yes | Configuration revision. |
owner_team_id | string | Yes | Responsible organization team. |
IntegrationPatch object
The IntegrationPatch object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
name | string | No | Replacement display name. |
description | string | No | Replacement purpose; empty clears the description. |
enabled | boolean | No | true permits authorized exchange; false blocks subsequent exchange without deleting copies. |
ExternalRecordWrite object
The ExternalRecordWrite object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
kind | string | Yes | Immutable record category after creation. Values: service, deployment, ticket. |
name | string | Yes | Name shown beside mapped native resources. |
url | string | Yes | HTTPS link to the source record; credentials and fragments are rejected. |
state | string | Yes | External lifecycle summary, not a Guard enforcement result. Values: unknown, active, resolved. |
labels | object | No | Selected label keys and string values; at most 20 entries. Default: {}. |
Creation requires absence through If-None-Match: *; replacement requires the current ETag. Record kind cannot change. A deleted and recreated external ID receives a replacement resource key; earlier mappings remain stale.
ExternalRecord object
The ExternalRecord object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
external_id | string | Yes | Integration-scoped external identity. |
integration_id | string | Yes | Owning integration. |
resource_key | string | Yes | Connector identity used by resource mappings. |
revision | integer | Yes | Connector-assigned revision. |
record | ExternalRecordWrite | Yes | Structure defined by the ExternalRecordWrite schema. |
received_at | string | Yes | Acceptance time. |
Event object
The Event object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
schema_version | integer | Yes | Envelope format version. Required value: 1. |
event_id | string | Yes | Stable event identity across attempts and replay. |
type | string | Yes | Event category. Values: inventory.upserted, inventory.removed, security.summary.updated, external.record.updated, external.record.removed, connection.state.changed, mapping.changed, operation.completed, subscription.test. |
organization_id | string | Yes | Owning Solarius organization. |
connection_id | string | Yes | Approved connection. |
grant_revision | integer | Yes | Grant generation at event creation. |
occurred_at | string | Yes | Time the source observation occurred. |
recorded_at | string | Yes | Time the transport journal accepted the event. |
test | boolean | Yes | true identifies a synthetic test; false identifies a source observation. |
data | object | Yes | Structure defined by the object schema. |
SubscriptionCreate object
The SubscriptionCreate object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
connection_id | string | Yes | Connection whose approved events are delivered. |
destination_url | string | Yes | Public HTTPS receiver without credentials; private addresses and redirects are rejected. |
event_types | string[] | Yes | Explicit types; subscription.test is reserved for test requests. |
enabled | boolean | No | Creation must use false; enabling requires a successful test. Default: false. Required value: false. |
SubscriptionPatch object
The SubscriptionPatch object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
destination_url | string | No | Replacement public HTTPS receiver; clears the successful test. |
event_types | string[] | No | Replacement selection; changing it clears the successful test. |
enabled | boolean | No | true requires a successful test for the saved URL and filters; false stops subsequent deliveries. |
Subscription object
The Subscription object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | Yes | Subscription identity. |
connection_id | string | Yes | Bound connection. |
destination_host | string | Yes | Receiver host; full URL is not returned. |
event_types | string[] | Yes | Selected types. |
enabled | boolean | Yes | Whether new deliveries are scheduled. |
revision | integer | Yes | Configuration revision. |
test_state | string | Yes | Result for the saved configuration. Values: not_tested, queued, delivered, failed. |
SigningSecret object
The SigningSecret object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | Yes | Secret version identity for Connector-Secret-Id. |
secret | string | No | Base64 encoding of 32 random bytes; present only in the first creation response and omitted on idempotent replay. |
created_at | string | Yes | Creation time. |
SubscriptionCreated object
The SubscriptionCreated object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
subscription | Subscription | Yes | Structure defined by the Subscription schema. |
signing_secret | SigningSecret | Yes | Structure defined by the SigningSecret schema. |
Delivery object
The Delivery object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | Yes | Delivery identity. |
event_id | string | Yes | Stable source event identity. |
state | string | Yes | Receiver admission state. Values: queued, retrying, delivered, failed, suppressed. |
attempt_count | integer | Yes | Attempts in this delivery window. |
last_status | integer or null | Yes | Last HTTP status; null for transport failures or no attempt. |
retry_deadline | string | Yes | End of the retry window, bounded by journal expiry. |
Operation object
The Operation object has the following fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | Yes | Connector operation identity. |
state | string | Yes | Execution result. Values: queued, running, reconciling, succeeded, failed, canceled. |
cancelable | boolean | Yes | Whether uncommitted work can be canceled. |
revision | integer | Yes | Operation revision for a cancellation precondition. |
result | object | Yes | Structure defined by the object schema. |
error | object or null | Yes | Null on success; failure code and recovery detail otherwise. |