---
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-05-13T22:51:26.2881412\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": "0f80ba1b6ba7c8ff312d07476690897fad33235f352f49ff11041b8b49b9777b",
  "hash_sha256_hex": null,
  "sig_alg": "ed25519",
  "sig_b64": "0UDaEJ3p6kI7Q38QGYZQPHqUrZAgN5X1V97dT9xIKXtHAt9zxFGLkbPUvS2tyw4IKT9c6aEa_PWF3WhgVIt5Bw",
  "pubkey_b64": "h-awvV8Rn-juph_c2Y7UH5A6e7NaFia3zBiMrJUOMOo",
  "x509_chain_pem": [
    "-----BEGIN CERTIFICATE-----\nMIIB9DCCAaagAwIBAgIQBrrNsmRlBvKQdA4idEliJjAFBgMrZXAwLjEsMCoGA1UE\nAwwjWEkgT2JqZWN0cyBJbmMgQ29udHJvbCBJbnRlcm1lZGlhdGUwHhcNMjYwNTEz\nMjI0NjA1WhcNMjYwNjEyMjI0NjA1WjBLMR4wHAYDVQQDDBV4aW8tY29udGVudC1w\ndWJsaXNoZXIxFzAVBgNVBAoMDlhJIE9iamVjdHMgSW5jMRAwDgYDVQQLDAdDb250\nZW50MCowBQYDK2VwAyEAh\u002BawvV8Rn\u002Bjuph/c2Y7UH5A6e7NaFia3zBiMrJUOMOqj\ngbwwgbkwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYI\nKwYBBQUHAyQwZQYDVR0jBF4wXIAUOym3mFmw/qs1fgKrujCkxhrTk7KhLqQsMCox\nKDAmBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0GCFFJgN/ix\nQn72H6h3T5lEr9f8lJQFMB0GA1UdDgQWBBS1LSJi5\u002BeqBq8h974Ht9HTgIcdgTAF\nBgMrZXADQQCKjXbPwnk/DZHmLQstUWRzU6GSf\u002BSHTXTTZCtRLbmJKxT17Qlbpexc\nsRgdSpxNWpJPe9Fr4vwhRkESMqMIpgQO\n-----END CERTIFICATE-----\n",
    "-----BEGIN CERTIFICATE-----\nMIIByDCCAXqgAwIBAgIUUmA3\u002BLFCfvYfqHdPmUSv1/yUlAUwBQYDK2VwMCoxKDAm\nBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0EwHhcNMjUxMTAy\nMDMxNzEyWhcNMzAxMTAxMDMxNzEyWjAuMSwwKgYDVQQDDCNYSSBPYmplY3RzIElu\nYyBDb250cm9sIEludGVybWVkaWF0ZTAqMAUGAytlcAMhAFSS/pggSRmTcAMko7uc\nATH8OHgxVymd5mBFlPXbJkgio4GtMIGqMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYD\nVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBQ7KbeYWbD\u002BqzV\u002BAqu6MKTGGtOTsjBlBgNV\nHSMEXjBcgBQAZRTDswSVORu\u002BkUOKX6WvrOvmQKEupCwwKjEoMCYGA1UEAwwfSW5z\ndGl0dXRlIG9mIFByb3ZlbmFuY2UgUm9vdCBDQYIUJqoJlpiSFg\u002B7W5IJLMrLttgR\nQp4wBQYDK2VwA0EA5FOht7YOsVRPp/FOKMQ\u002B3Mo9JxrvGR3ylKWAWNm6OUV7N3DB\nI9cD62wU5I0d0EKDBy0CX9DnoqUyxv5yguraAA==\n-----END CERTIFICATE-----\n",
    "-----BEGIN CERTIFICATE-----\nMIIBaTCCARugAwIBAgIUJqoJlpiSFg\u002B7W5IJLMrLttgRQp4wBQYDK2VwMCoxKDAm\nBgNVBAMMH0luc3RpdHV0ZSBvZiBQcm92ZW5hbmNlIFJvb3QgQ0EwHhcNMjUxMTAy\nMDMwNTEyWhcNMzUxMDMxMDMwNTEyWjAqMSgwJgYDVQQDDB9JbnN0aXR1dGUgb2Yg\nUHJvdmVuYW5jZSBSb290IENBMCowBQYDK2VwAyEAEWNZl\u002Br3IC7\u002BgBh90Yo1kWk1\npZCVzVuFdFT7qBBU8W2jUzBRMB0GA1UdDgQWBBQAZRTDswSVORu\u002BkUOKX6WvrOvm\nQDAfBgNVHSMEGDAWgBQAZRTDswSVORu\u002BkUOKX6WvrOvmQDAPBgNVHRMBAf8EBTAD\nAQH/MAUGAytlcANBAO6QeydOFNrN75qNyftggYudsxMyl4w9qWkSdZ6hlhrRcbSr\niG9Si0kbrIJOwYB/LTBU0RM4Rl\u002Bo9PM3Qp0mPwo=\n-----END CERTIFICATE-----\n"
  ],
  "key_id": "SDyVO7FvlAM-6CvQ62VZYOBO7JADFqLquUunUABRgKg",
  "created_at": "2026-05-13T22:51:26Z"
}
-->