---
title: "API Reference"
description: "API reference for the XI Objects client library, wire protocol, and Orbital endpoints."
published: 2026-02-18T18:06:44.655944+00:00
updated: 2026-02-18T18:06:44.655944+00:00
url: https://xiobjects.com/docs/xio/api
source: XI Objects
---

<!-- xion:doctype xion+markdown -->
<!-- xion:metadata
{
  "version": "1.0",
  "content_type": "application/xion\u002Bmarkdown",
  "source_type": "xi-content/doc",
  "generator": "xio-content-publisher/1.0.0",
  "generated": "2026-02-18T18:04:33.8186988\u002B00:00",
  "encoding": "utf-8",
  "render_intent": "markdown",
  "title": "API Reference",
  "slug": "xio/api",
  "copyright": "\u00A9 2026 XI Objects Inc"
}
-->

# API Reference

This section provides detailed documentation for the XI Objects API surface, including the .NET client library, the XIO wire protocol, and the Orbital service endpoints.

## Client Library

The primary way to interact with XI Objects is through the **Xio.Client** .NET library. The client handles wire protocol encoding, caching, retry logic, and Sparse Merkle proof verification.

### Registration via Dependency Injection

```csharp
using Xio.Client;

services.AddXioClient(options =>
{
    options.OrbitalEndpoints = new[] { "https://orbital.example.com" };
    options.EnableCaching = true;
    options.EnableProofVerification = true;
});
```

### Key Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| `OrbitalEndpoints` | `IReadOnlyList<string>` | List of Orbital node endpoints to query |
| `QueryTimeout` | `TimeSpan` | Timeout for individual queries |
| `MaxRetryAttempts` | `int` | Maximum retry attempts per query |
| `EnableCaching` | `bool` | Enable in-memory response caching |
| `EnableProofVerification` | `bool` | Verify Sparse Merkle proofs on responses |

### Core Services

The client library exposes several services through dependency injection:

| Service | Interface | Purpose |
|---------|-----------|---------|
| Client | `IXioClientService` | Main facade for XI Objects operations |
| Resolver | `IXioResolverService` | Resolve `.xio` domain queries via wire protocol |
| Cache | `IXioCacheService` | In-memory cache with stale-while-revalidate |
| Verification | `IXioVerificationService` | Sparse Merkle proof verification |
| Discovery | `IOrbitalDiscoveryService` | Discover available Orbital endpoints |
| Configuration | `IXioClientConfigurationService` | Runtime configuration management |

## Wire Protocol

The XIO wire protocol is a custom DNS-like binary protocol. Clients build `XioMessage` objects, serialize them to binary, and POST to the Orbital `/query` endpoint.

### Message Structure

```
┌──────────────────────────────────┐
│  Header (TransactionId, Flags,   │
│  OpCode, ResponseCode, Counts)   │
├──────────────────────────────────┤
│  Question Section                │
│  (DomainName, RecordType, Class) │
├──────────────────────────────────┤
│  Answer Section                  │
│  (Resource Records)              │
├──────────────────────────────────┤
│  Authority Section               │
│  (Authoritative Records)         │
├──────────────────────────────────┤
│  Additional Section              │
│  (Proofs, supplementary data)    │
└──────────────────────────────────┘
```

### OpCodes

| OpCode | Description |
|--------|-------------|
| `Query` | Standard record lookup |
| `Issue` | Certificate or record issuance |
| `Revoke` | Certificate or record revocation |
| `Proof` | Request Sparse Merkle proof |
| `Head` | Request current state head (epoch) |
| `Meta` | Metadata query |

### Record Types

| Type | Value | Description |
|------|-------|-------------|
| `A` | 1 | IPv4 address record |
| `CNAME` | 5 | Canonical name |
| `TXT` | 16 | Text data |
| `AAAA` | 28 | IPv6 address record |
| `XIO` | 65001 | Signed data record |
| `Proof` | 65002 | Sparse Merkle Tree proof |
| `XSIGN` | 65003 | Signing metadata: certificate chain, signatures, attribution |
| `XFPR` | 65004 | Fingerprint record: composite feature set for content identity |

## Orbital Endpoints

Orbital nodes expose HTTP endpoints for protocol queries and administrative operations.

### Query Endpoints

| Method | Endpoint | Content-Type | Description |
|--------|----------|--------------|-------------|
| POST | `/query` | `application/octet-stream` | Binary wire protocol query |
| POST | `/query/json` | `application/json` | JSON convenience query (domain + recordType) |
| POST | `/search/fingerprint` | `application/json` | Spectral fingerprint similarity search |

### Record Management (Authenticated)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/records` | Publish records |
| POST/GET | `/records/delta` | Delta replication between peers |
| GET | `/records/peers` | Peer discovery |
| GET | `/records/snapshot` | Full state snapshot |

### Control Module (Certified Orbitals Only)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/control/pki/issue` | Issue leaf certificate |
| POST | `/control/pki/revoke` | Revoke certificate |
| GET | `/control/pki/certificates/{keyId}` | Get certificate by key ID |
| GET | `/control/pki/state/root` | Current SMT state root |
| GET | `/control/epoch/config` | Epoch configuration |
| GET | `/control/status` | Control module activation status |

See the individual sub-sections for detailed documentation on [signing & trust blocks](/docs/xio/api/signing) and [fingerprint search](/docs/xio/api/fingerprinting).
<!-- xion:trust
{
  "v": 1,
  "canon_v": 1,
  "ctx": "xiobjects.com/content",
  "hash_blake3_hex": "0ed616970cfee415140df2d7e1a15757dde94bf8f659cc7aad3f65a76bdbf5fb",
  "hash_sha256_hex": null,
  "sig_alg": "ed25519",
  "sig_b64": "vw_O0nl_3TgFv8XAmQzq0xoRmLNG-54I-0OvCrvRM5Xhp1hF5SHz8djL9x4wO4aptGJrnRdW5DIsfiU6L_H8Dg",
  "pubkey_b64": "ff4Npz7sRQH_vUn9FY8Wrc8v_00Z49h15EyQgKVTHR0",
  "x509_chain_pem": [
    "-----BEGIN CERTIFICATE-----\r\nMIIB9TCCAaegAwIBAgIRAM4lRb8aI/FYHOJD5OYqefQwBQYDK2VwMC4xLDAqBgNV\r\nBAMMI1hJIE9iamVjdHMgSW5jIENvbnRyb2wgSW50ZXJtZWRpYXRlMB4XDTI2MDIx\r\nNTIyMDg0OFoXDTI2MDMxNzIyMDg0OFowSzEeMBwGA1UEAwwVeGlvLWNvbnRlbnQt\r\ncHVibGlzaGVyMRcwFQYDVQQKDA5YSSBPYmplY3RzIEluYzEQMA4GA1UECwwHQ29u\r\ndGVudDAqMAUGAytlcAMhAH3\u002BDac\u002B7EUB/71J/RWPFq3PL/9NGePYdeRMkIClUx0d\r\no4G8MIG5MAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG\r\nCCsGAQUFBwMkMGUGA1UdIwReMFyAFDspt5hZsP6rNX4Cq7owpMYa05OyoS6kLDAq\r\nMSgwJgYDVQQDDB9JbnN0aXR1dGUgb2YgUHJvdmVuYW5jZSBSb290IENBghRSYDf4\r\nsUJ\u002B9h\u002Bod0\u002BZRK/X/JSUBTAdBgNVHQ4EFgQUP5BTxnjCAxVKgMvFhx40ljlGOAkw\r\nBQYDK2VwA0EAjKlSBzHgXpPM2PA\u002BSJ/rMso5OEqtWIHGo/zr2QSuZRXhSWafIbk9\r\nZnl0kKZCqUB2HpCfgnpOGCPK6SlefwQsAQ==\r\n-----END CERTIFICATE-----\r\n",
    "-----BEGIN CERTIFICATE-----\r\nMIIByDCCAXqgAwIBAgIUUmA3\u002BLFCfvYfqHdPmUSv1/yUlAUwBQYDK2VwMCoxKDAm\r\nBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0EwHhcNMjUxMTAy\r\nMDMxNzEyWhcNMzAxMTAxMDMxNzEyWjAuMSwwKgYDVQQDDCNYSSBPYmplY3RzIElu\r\nYyBDb250cm9sIEludGVybWVkaWF0ZTAqMAUGAytlcAMhAFSS/pggSRmTcAMko7uc\r\nATH8OHgxVymd5mBFlPXbJkgio4GtMIGqMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYD\r\nVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBQ7KbeYWbD\u002BqzV\u002BAqu6MKTGGtOTsjBlBgNV\r\nHSMEXjBcgBQAZRTDswSVORu\u002BkUOKX6WvrOvmQKEupCwwKjEoMCYGA1UEAwwfSW5z\r\ndGl0dXRlIG9mIFByb3ZlbmFuY2UgUm9vdCBDQYIUJqoJlpiSFg\u002B7W5IJLMrLttgR\r\nQp4wBQYDK2VwA0EA5FOht7YOsVRPp/FOKMQ\u002B3Mo9JxrvGR3ylKWAWNm6OUV7N3DB\r\nI9cD62wU5I0d0EKDBy0CX9DnoqUyxv5yguraAA==\r\n-----END CERTIFICATE-----\r\n",
    "-----BEGIN CERTIFICATE-----\r\nMIIBaTCCARugAwIBAgIUJqoJlpiSFg\u002B7W5IJLMrLttgRQp4wBQYDK2VwMCoxKDAm\r\nBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0EwHhcNMjUxMTAy\r\nMDMwNTEyWhcNMzUxMDMxMDMwNTEyWjAqMSgwJgYDVQQDDB9JbnN0aXR1dGUgb2Yg\r\nUHJvdmVuYW5jZSBSb290IENBMCowBQYDK2VwAyEAEWNZl\u002Br3IC7\u002BgBh90Yo1kWk1\r\npZCVzVuFdFT7qBBU8W2jUzBRMB0GA1UdDgQWBBQAZRTDswSVORu\u002BkUOKX6WvrOvm\r\nQDAfBgNVHSMEGDAWgBQAZRTDswSVORu\u002BkUOKX6WvrOvmQDAPBgNVHRMBAf8EBTAD\r\nAQH/MAUGAytlcANBAO6QeydOFNrN75qNyftggYudsxMyl4w9qWkSdZ6hlhrRcbSr\r\niG9Si0kbrIJOwYB/LTBU0RM4Rl\u002Bo9PM3Qp0mPwo=\r\n-----END CERTIFICATE-----\r\n"
  ],
  "key_id": "-GCB4sEBzFethc5Pd0Rzyn_6ySyHB4QaqD9DAoW9ViE",
  "created_at": "2026-02-18T18:04:33Z"
}
-->