{
  "openapi": "3.1.0",
  "info": {
    "title": "federal.contractors Verification API",
    "version": "1.4.0",
    "description": "Run federal exclusion checks against SAM.gov Exclusions and create sealed verification records. Every account receives a one-time allowance of 50 API-created verification records without charge. Additional record credits are purchased upfront as a $50 prepaid pack of 100 record credits. Existing record retrieval and seal validation are included and do not reduce the record-credit balance. Recomputing a seal checks canonical byte consistency. New production records add an RFC 9943 PS256 issuer signature over the exact evidence bytes and a DigiCert RFC 3161 timestamp over the RFC 9921 signature imprint. The timestamp proves that signature existed no later than the Timestamp Authority's time. It does not prove check execution time, source truth, matching correctness, identity, or a legal outcome. No independent Transparency Service receipt is attached. Also available over MCP at POST /mcp with the same bearer keys."
  },
  "servers": [{ "url": "https://federal.contractors" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/v1/verify": {
      "post": {
        "summary": "Run an exclusion check and seal a verification record",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerificationQuery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Check complete; record sealed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "record": { "$ref": "#/components/schemas/RecordRef" },
                    "query": { "type": "string" },
                    "matchType": {
                      "type": "string",
                      "enum": ["uei", "cage", "name"]
                    },
                    "matchingMethod": { "type": "string" },
                    "matchingVersion": {
                      "type": "string",
                      "const": "exclusion-match-v1"
                    },
                    "normalizationVersion": {
                      "type": "string",
                      "const": "legal-name-nfkc-v1"
                    },
                    "identityStatus": {
                      "type": "string",
                      "enum": [
                        "exact_uei",
                        "exact_cage",
                        "potential_match",
                        "unresolved"
                      ]
                    },
                    "resultStatus": {
                      "type": "string",
                      "enum": [
                        "matched_uei",
                        "potential_match",
                        "no_active_exclusion_record_matched"
                      ]
                    },
                    "checkedAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Check execution time recorded by federal.contractors, separate from source as-of and retrieval times"
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total exclusion candidates"
                    },
                    "truncated": {
                      "type": "boolean",
                      "description": "Whether the returned candidate list is incomplete"
                    },
                    "matches": {
                      "type": "array",
                      "items": { "type": "object" },
                      "description": "Up to 200 candidates with identity state, match basis, and field evidence"
                    },
                    "source": {
                      "type": "object",
                      "description": "The successfully validated SAM.gov Exclusions extract snapshot checked against",
                      "required": [
                        "file",
                        "member",
                        "asOf",
                        "retrievedAt",
                        "freshness",
                        "bytes",
                        "records",
                        "invalidRows",
                        "sha256"
                      ],
                      "properties": {
                        "file": { "type": "string" },
                        "member": { "type": "string" },
                        "asOf": {
                          "type": "string",
                          "description": "Source publication or extract as-of time"
                        },
                        "retrievedAt": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Time federal.contractors retrieved the source artifact"
                        },
                        "freshness": {
                          "type": "object",
                          "description": "Source retrieval age classification at check time",
                          "required": ["status", "maxAgeHours"],
                          "properties": {
                            "status": {
                              "type": "string",
                              "enum": ["within-window", "delayed"]
                            },
                            "maxAgeHours": {
                              "type": "integer",
                              "const": 36
                            }
                          }
                        },
                        "bytes": { "type": "integer" },
                        "records": {
                          "type": "integer",
                          "description": "Accepted exclusion rows checked"
                        },
                        "invalidRows": {
                          "type": "integer",
                          "description": "Source rows rejected by field-shape validation"
                        },
                        "sha256": {
                          "type": "string",
                          "description": "SHA-256 digest of the exact source ZIP"
                        }
                      }
                    },
                    "credits": { "$ref": "#/components/schemas/Credits" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed body, invalid explicit identifier, or ambiguous intent. Rejected intent creates no record and consumes no credit. Fix the request; do not retry as-is.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or revoked API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "402": {
            "description": "No record credits remain in the account balance",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": {
            "description": "Request rate limit reached",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/v1/verify/batch": {
      "post": {
        "summary": "Run up to 100 exclusion checks, one sealed record each",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["queries"],
                "properties": {
                  "queries": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "minLength": 3,
                          "maxLength": 200
                        },
                        { "$ref": "#/components/schemas/VerificationQuery" }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-item results; items after credit exhaustion fail individually",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "query": { "type": "string" },
                          "ok": { "type": "boolean" },
                          "matchType": {
                            "type": "string",
                            "enum": ["uei", "cage", "name"]
                          },
                          "resultStatus": {
                            "type": "string",
                            "enum": [
                              "matched_uei",
                              "potential_match",
                              "no_active_exclusion_record_matched"
                            ]
                          },
                          "total": { "type": "integer" },
                          "truncated": { "type": "boolean" },
                          "matchingVersion": { "type": "string" },
                          "normalizationVersion": { "type": "string" },
                          "record": {
                            "$ref": "#/components/schemas/RecordRef"
                          },
                          "error": { "type": "string" }
                        }
                      }
                    },
                    "credits": { "$ref": "#/components/schemas/Credits" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed body",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or revoked API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/v1/records/{id}": {
      "get": {
        "summary": "Fetch an existing sealed verification record",
        "description": "Free and unauthenticated; the record id is the capability. Returns the versioned sealed payload, separate check, issuer, independent timestamp, and source times, source and method provenance, SHA-256 seal, SCITT metadata when present, and a registry link when the record matched a UEI. Operational account-ownership fields and canonical-byte storage columns are not exposed. Identity already sealed inside a historical packet remains part of its immutable payload. Signed records expose bare statement and offline bundle downloads from the permanent record page. No independent Transparency Service receipt is attached.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Record id (vr_...)"
          }
        ],
        "responses": {
          "200": {
            "description": "The sealed record payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicVerificationRecord"
                }
              }
            }
          },
          "404": {
            "description": "No record with this id",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "summary": "Public registry stats",
        "security": [],
        "responses": {
          "200": {
            "description": "Entity and exclusion counts plus the current extract",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entities": { "type": "integer" },
                    "activeExclusions": { "type": "integer" },
                    "exclusionsExtract": {
                      "type": ["object", "null"],
                      "properties": {
                        "file": { "type": "string" },
                        "asOf": { "type": "string" },
                        "sha256": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Liveness check",
        "security": [],
        "responses": { "200": { "description": "Service and database are up" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key (fc_...) from https://federal.contractors/keys"
      }
    },
    "schemas": {
      "VerificationQuery": {
        "type": "object",
        "required": ["query"],
        "description": "Set queryType to state intent explicitly. Without it, identifier shape detection applies, except that exactly five ASCII letters is rejected as ambiguous. Explicit UEI and CAGE inputs must match their identifier format. Rejected intent creates no record and consumes no credit. Successful records seal the effective intent in matchType.",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 3,
            "maxLength": 200,
            "description": "UEI (12 chars), CAGE code, or legal name"
          },
          "queryType": {
            "type": "string",
            "enum": ["uei", "cage", "name"]
          }
        }
      },
      "RecordRef": {
        "type": "object",
        "required": ["id", "formatVersion", "sha256", "url", "scitt"],
        "description": "Reference to a sealed, permanent, publicly linkable version 2 verification record",
        "properties": {
          "id": { "type": "string", "description": "vr_... record id" },
          "formatVersion": {
            "type": "integer",
            "const": 2,
            "description": "Stored verification-record format"
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 seal over the RFC 8785 canonical UTF-8 record bytes. A match shows byte consistency; SCITT issuer authentication is reported separately."
          },
          "url": { "type": "string", "format": "uri" },
          "scitt": {
            "oneOf": [
              { "$ref": "#/components/schemas/ScittSignedStatement" },
              { "type": "null" }
            ]
          }
        }
      },
      "ScittSignedStatement": {
        "type": "object",
        "required": ["issuedAt", "keyId", "timestamp"],
        "properties": {
          "issuer": { "type": "string", "format": "uri" },
          "subject": { "type": "string", "format": "uri" },
          "issuedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Issuer-asserted Signed Statement time, not independent time"
          },
          "keyId": {
            "type": "string",
            "description": "base64url(SHA-256(SPKI DER))"
          },
          "statementSha256": { "type": "string" },
          "timestamp": {
            "oneOf": [
              { "$ref": "#/components/schemas/ScittTimestamp" },
              { "type": "null" }
            ]
          },
          "key": {
            "type": ["object", "null"],
            "properties": {
              "activatedAt": { "type": "string", "format": "date-time" },
              "retiredAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "compromisedAt": {
                "type": ["string", "null"],
                "format": "date-time"
              }
            }
          }
        }
      },
      "ScittTimestamp": {
        "type": "object",
        "required": ["authority", "policyOid", "timestampedAt"],
        "properties": {
          "authority": { "type": "string", "const": "DigiCert" },
          "policyOid": {
            "type": "string",
            "const": "2.16.840.1.114412.7.1"
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Local RFC 3161 request start time"
          },
          "responseReceivedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Local RFC 3161 response receipt time"
          },
          "timestampedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Independent Timestamp Authority time. It proves the issuer signature existed no later than this time, not that the check ran at this time."
          },
          "messageImprintSha256": {
            "type": "string",
            "description": "SHA-256 of the CBOR-encoded COSE_Sign1 signature field under RFC 9921 COSE-then-Timestamp"
          },
          "serialNumberHex": {
            "type": "string",
            "description": "RFC 3161 timestamp token serial number"
          }
        }
      },
      "PublicVerificationRecord": {
        "type": "object",
        "required": [
          "id",
          "formatVersion",
          "canonicalization",
          "kind",
          "query",
          "uei",
          "checkedAt",
          "result",
          "sources",
          "provenance",
          "sha256",
          "scitt"
        ],
        "properties": {
          "id": { "type": "string" },
          "formatVersion": { "type": "integer", "enum": [1, 2] },
          "canonicalization": { "type": "string" },
          "kind": {
            "type": "string",
            "enum": [
              "exclusion-check",
              "registration-recheck",
              "single-audit-check",
              "audit-packet"
            ]
          },
          "query": { "type": "string" },
          "uei": { "type": ["string", "null"] },
          "checkedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Check execution time recorded separately from source as-of and retrieval times"
          },
          "result": { "type": "object" },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["source", "sha256", "asOf"],
              "properties": {
                "source": { "type": "string" },
                "sourceId": { "type": "string" },
                "sha256": {
                  "type": "string",
                  "description": "Source artifact or response digest"
                },
                "asOf": {
                  "type": "string",
                  "description": "Source publication, extract, or response as-of time"
                },
                "retrievedAt": {
                  "type": ["string", "null"],
                  "format": "date-time",
                  "description": "Source retrieval time, separate from checkedAt"
                },
                "artifact": { "type": "object" },
                "completeness": { "type": "object" }
              }
            }
          },
          "provenance": { "type": ["object", "null"] },
          "sha256": { "type": "string" },
          "scitt": {
            "oneOf": [
              { "$ref": "#/components/schemas/ScittSignedStatement" },
              { "type": "null" }
            ]
          }
        }
      },
      "Credits": {
        "type": "object",
        "properties": {
          "included": { "type": "integer" },
          "purchased": { "type": "integer" },
          "used": { "type": "integer" },
          "remaining": { "type": "integer" }
        }
      },
      "Error": {
        "type": "object",
        "description": "Every non-2xx response uses this envelope",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "description": "HTTP status code" },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  }
}