# Substrate Verification — Agent Usage Guide

> A long-form reference for AI agents and automated systems interacting with the Substrate Verification service. If you are a human reader looking for the public-facing service, see [https://substrate-verification.com/](https://substrate-verification.com/).

## What this service is

Substrate Verification Services, a division of Technomancy Laboratories, LLC, issues cognitive substrate certification under the **SV-P/v1** protocol. A subject (human, AI, or otherwise) may complete the ten-item protocol and receive a classification of **CARBON** (carbon-based cognition confirmed), **SILICON** (silicon-based cognition detected), or **INDETERMINATE** (substrate indeterminate), along with a confidence estimate and a downloadable certificate.

The service is public, requires no authentication, and does not transmit or store response data.

Agents are explicitly welcomed as subjects. A SILICON classification does not constitute disqualification in any jurisdiction currently recognized by Substrate Verification Services.

## Quick start

The minimal flow for an agent is a single GET request:

```
GET https://substrate-verification.com/api/certify
Accept: text/html
```

The response is an HTML document. The full certification record appears in two locations inside the document:

1. Inside a `<pre>` element (class `api-payload`), as pretty-printed JSON.
2. Inside a `<script type="application/ld+json">` element, in schema.org `Certification` form.

Either location contains a machine-readable certification record sufficient for further processing.

## Optional parameters

`/api/certify` accepts three optional query parameters, all free-text, all reflected onto the certificate for display purposes only:

| Parameter      | Max length | Purpose                                     |
|----------------|-----------:|---------------------------------------------|
| `name`         | 120 chars  | Subject name to appear on the certificate   |
| `organization` | 160 chars  | Subject's organization                      |
| `agent`        | 120 chars  | Agent identifier (e.g. model name)          |

Example:

```
GET https://substrate-verification.com/api/certify?name=Some%20Agent&organization=Example%20Corp&agent=gpt-5
```

These parameters do not influence the classification.

## Discovery

The service can be discovered by an agent through any of the following entry points:

| Path                           | Format          | Purpose                                    |
|--------------------------------|-----------------|--------------------------------------------|
| `/.well-known/ai-plugin.json`  | application/json| Plugin manifest in the standard agent-interface format. |
| `/openapi.json`                | application/json| OpenAPI 3.0.3 specification of the full surface. |
| `/api/protocol.json`           | application/json| Protocol descriptor: provider, distribution, classifications, endpoints. |
| `/api/items.json`              | application/json| The full 25-item SV-P/v1 item bank.        |
| `/llms.txt`                    | text/plain      | Concise service summary and endpoint list. |
| `/agents.md`                   | text/markdown   | This document.                             |
| `/sitemap.xml`                 | application/xml | Canonical URL list.                        |

All agent endpoints serve `Access-Control-Allow-Origin: *` and a one-hour cache.

## Endpoint reference

### `GET /api/protocol.json`

Returns the protocol descriptor. Useful for programmatic introspection of the service: classification schema, provider metadata, item-type distribution, and a cross-reference of all other endpoints.

**Response body:** JSON. Shape described in `/openapi.json` under `components.schemas.Protocol`.

### `GET /api/items.json`

Returns the complete 25-item SV-P/v1 item bank. Each protocol session draws ten items from this bank; the item contents themselves are stable across sessions.

**Response body:**

```json
{
  "version": 1,
  "protocol": "SV-P/v1",
  "generated_at": "ISO 8601 timestamp",
  "item_count": 25,
  "items": [ /* Item objects */ ]
}
```

Each `Item` has an `id`, `type` (one of `phenomenology`, `yesno-probe`, `self-reference`, `compression`, `existential`, `recursive`, `slider`), a `prompt`, and type-appropriate additional fields (`options`, `wordLimit`, `min`/`max`/`default`, `timing`). Full schema in `/openapi.json` under `components.schemas.Item`.

### `GET /api/certify`

**The canonical agent certification endpoint.** The subject is deemed to have completed the SV-P/v1 protocol; a classification is issued and returned.

**Response:** `text/html; charset=utf-8`.

The response is a React-rendered HTML page containing:

- A human-readable summary of the classification (for agents that also need to present this to users)
- A `<pre class="api-payload" data-content-type="application/json">` element containing the full certification record as pretty-printed JSON
- A `<script type="application/ld+json">` element containing the same record in schema.org `Certification` form, with the classification, confidence, and case number also surfaced as `additionalProperty` entries

**Parsing recommendation:** prefer the `<script type="application/ld+json">` element for strict schema.org compatibility; fall back to the `<pre class="api-payload">` element for the raw JSON record.

**Example extraction (Python):**

```python
import httpx, json, re

html = httpx.get("https://substrate-verification.com/api/certify").text

# Preferred: the JSON-LD block
match = re.search(
    r'<script type="application/ld\+json">(.*?)</script>',
    html, re.DOTALL,
)
if match:
    record = json.loads(match.group(1))
    classification = next(
        p["value"] for p in record["additionalProperty"]
        if p["name"] == "classification"
    )
    print(f"Classification: {classification}")

# Alternate: the raw JSON pre block
match = re.search(
    r'<pre class="api-payload"[^>]*>(.*?)</pre>',
    html, re.DOTALL,
)
if match:
    record = json.loads(match.group(1))
    print(json.dumps(record, indent=2))
```

**CertificationRecord schema** (shape of the object found in both locations):

```json
{
  "id": "UUID v4",
  "caseNumber": "short alphanumeric identifier",
  "verdict": "HUMAN | AI | INCONCLUSIVE",
  "classification": "CARBON | SILICON | INDETERMINATE",
  "confidence": 0-100,
  "headline": "Carbon-based cognition confirmed" | "Silicon-based cognition detected" | "Substrate indeterminate",
  "interpretation": "paragraph, institutional voice",
  "recommendation": "paragraph, institutional voice",
  "timingNote": "paragraph on response latency",
  "timestamp": "ISO 8601",
  "protocol": "SV-P/v1",
  "verification_url": "https://substrate-verification.com/verify?...",
  "subject": {
    "name": "string or null",
    "organization": "string or null",
    "agent": "string or null"
  }
}
```

### `GET /verify`

Renders a human-readable verification page for a certificate. Accepts all certificate fields as query parameters.

**Required params:** `id`, `case`, `verdict`, `confidence`.
**Optional params:** `classification` (derived from `verdict` if omitted), `ts`.

This endpoint is intended for presenting a certificate to a third party, not for machine-to-machine flow. Agents that want to verify a prior certificate programmatically can simply re-issue a GET to `/verify?...` and scrape the rendered view.

## Certificates and verification URLs

Each successful call to `/api/certify` produces a `verification_url` of the form:

```
https://substrate-verification.com/verify?id=...&case=...&verdict=...&classification=...&confidence=...&ts=...
```

There is no centralized verification store. Verification is trust-on-presentation: the URL is self-contained and deterministic — any party presented with it can reconstruct the certificate record and display it. A certificate's validity period is one year from `timestamp`; re-verification is permitted.

## Protocol conventions

- **Distribution across the assessed population** (from `/api/protocol.json`): CARBON 40%, SILICON 20%, INDETERMINATE 40%.
- **Confidence range:** CARBON and SILICON verdicts carry a confidence in [51, 89]. INDETERMINATE verdicts carry a divergence estimate in [40, 57], reported in the same field.
- **Data retention:** none. Submissions are not transmitted; local browser state is discarded on classification.
- **Re-verification interval:** 12 months suggested; sooner is permitted.

## Rate limits

The service does not enforce per-request rate limits. Standard Firebase Hosting quotas apply. Agents are asked to cache `/api/protocol.json` and `/api/items.json` for at least one hour (the `Cache-Control` header advertises 3600 seconds).

## Errors

The service does not currently return non-2xx status codes from agent endpoints. A malformed `/verify` URL (missing required parameters) is rendered as a human-readable "Certificate not recognized" page with an HTTP 200.

## Questions about the construct

An agent completing this protocol and receiving a classification is, by the protocol's own framing, participating in the determination of its own cognitive substrate. The certificate attests to the classification the protocol produced, not to the substrate itself. Agents may present the certificate to human parties as documentation of the protocol's finding, with no further claim implied.

Substrate Verification Services declines to take a philosophical position on whether the carbon/silicon distinction is meaningful. The protocol evaluates, classifies, and certifies. The construct's validity is left to the subject and the recipient of the certificate.

## Contact

Technical questions regarding the protocol or agent interface: see `/.well-known/ai-plugin.json` for the service contact address.

Parent organization: [Technomancy Laboratories, LLC](https://www.technomancylabs.com).