{"openapi":"3.1.0","info":{"title":"PayAPIKey Reconciliation API","version":"2026-07-10","description":"Stateless normalization and reconciliation endpoints for authorized API gateways. The API does not store upstream credentials and does not require prompt or completion content."},"servers":[{"url":"https://www.payapikey.com"}],"tags":[{"name":"Reconciliation"},{"name":"Connectors"},{"name":"Examples"}],"paths":{"/api/v1/reconcile":{"post":{"tags":["Reconciliation"],"summary":"Reconcile normalized downstream, upstream, and payment ledgers","operationId":"reconcileLedgers","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconciliationInput"}}}},"responses":{"200":{"description":"Reconciliation report","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ReconciliationReport"}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/InvalidRequest"}}}},"/api/v1/normalize":{"post":{"tags":["Connectors"],"summary":"Normalize a native One API-family export","operationId":"normalizeConnectorPayload","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorPayload"}}}},"responses":{"200":{"description":"Canonical reconciliation input","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ReconciliationInput"}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}}}},"/api/v1/connectors":{"get":{"tags":["Connectors"],"summary":"List supported connector contracts and source mappings","operationId":"listConnectors","responses":{"200":{"description":"Connector catalog","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","status","manifestHref","capabilitySummary"],"properties":{"id":{"type":"string","enum":["new-api","one-api","one-hub","voapi"]},"name":{"type":"string"},"status":{"type":"string","enum":["verified","compatible","file-import","planned"]},"manifestHref":{"type":"string"},"capabilitySummary":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorCapability"}}},"additionalProperties":true}},"meta":{"$ref":"#/components/schemas/ConnectorCatalogMeta"}}}}}}}}},"/api/v1/connectors/{connectorId}/manifest":{"get":{"tags":["Connectors"],"summary":"Get a machine-readable connector manifest","description":"Returns source resource references, normalization mappings, capability support, and fixed security boundaries. Source endpoints are for caller-operated readers; the hosted service never pulls a supplied URL or accepts source credentials.","operationId":"getConnectorManifest","parameters":[{"name":"connectorId","in":"path","required":true,"description":"Stable connector identifier.","schema":{"type":"string","enum":["new-api","one-api","one-hub","voapi"]}}],"responses":{"200":{"description":"Connector manifest","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ConnectorManifest"}}}}}},"404":{"$ref":"#/components/responses/ConnectorNotFound"}}}},"/api/v1/examples/reconciliation":{"get":{"tags":["Examples"],"summary":"Get a complete example reconciliation bundle","operationId":"getReconciliationExample","responses":{"200":{"description":"Example payload","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ReconciliationInput"}}}}}}}}}},"components":{"schemas":{"ReconciliationInput":{"type":"object","additionalProperties":false,"required":["downstreamUsage"],"properties":{"version":{"type":"string","examples":["2026-07-10"]},"currency":{"type":"string","default":"USD"},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"downstreamUsage":{"type":"array","maxItems":5000,"items":{"type":"object","additionalProperties":false,"required":["requestId","occurredAt","model","status","chargedAmount"],"properties":{"requestId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"userId":{"type":"string"},"tokenId":{"type":"string"},"model":{"type":"string"},"channelId":{"type":"string"},"status":{"type":"string","enum":["success","failed","pending","refunded"]},"chargedAmount":{"oneOf":[{"type":"number","minimum":0,"examples":[0.018]},{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d+)?$","examples":["0.018"]}],"description":"Non-negative monetary amount in the record currency. Send either a JSON number or a canonical decimal string without exponent notation; the service calculates with Decimal arithmetic."},"refundAmount":{"oneOf":[{"type":"number","minimum":0,"examples":[0.018]},{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d+)?$","examples":["0.018"]}],"description":"Non-negative monetary amount in the record currency. Send either a JSON number or a canonical decimal string without exponent notation; the service calculates with Decimal arithmetic."},"expectedCharge":{"oneOf":[{"type":"number","minimum":0,"examples":[0.018]},{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d+)?$","examples":["0.018"]}],"description":"Non-negative monetary amount in the record currency. Send either a JSON number or a canonical decimal string without exponent notation; the service calculates with Decimal arithmetic."},"currency":{"type":"string","examples":["USD"]},"tokens":{"type":"object","additionalProperties":false,"properties":{"input":{"type":"number","minimum":0},"output":{"type":"number","minimum":0},"cacheRead":{"type":"number","minimum":0},"cacheWrite":{"type":"number","minimum":0},"reasoning":{"type":"number","minimum":0},"media":{"type":"number","minimum":0}}}}}},"upstreamCharges":{"type":"array","maxItems":5000,"items":{"type":"object","additionalProperties":false,"required":["occurredAt","model","status","costAmount"],"properties":{"requestId":{"type":"string"},"upstreamId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"model":{"type":"string"},"channelId":{"type":"string"},"status":{"type":"string","enum":["success","failed","pending","refunded"]},"costAmount":{"oneOf":[{"type":"number","minimum":0,"examples":[0.018]},{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d+)?$","examples":["0.018"]}],"description":"Non-negative monetary amount in the record currency. Send either a JSON number or a canonical decimal string without exponent notation; the service calculates with Decimal arithmetic."},"refundAmount":{"oneOf":[{"type":"number","minimum":0,"examples":[0.018]},{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d+)?$","examples":["0.018"]}],"description":"Non-negative monetary amount in the record currency. Send either a JSON number or a canonical decimal string without exponent notation; the service calculates with Decimal arithmetic."},"currency":{"type":"string","examples":["USD"]},"tokens":{"type":"object","additionalProperties":false,"properties":{"input":{"type":"number","minimum":0},"output":{"type":"number","minimum":0},"cacheRead":{"type":"number","minimum":0},"cacheWrite":{"type":"number","minimum":0},"reasoning":{"type":"number","minimum":0},"media":{"type":"number","minimum":0}}}}}},"payments":{"type":"array","maxItems":5000,"items":{"type":"object","additionalProperties":false,"required":["transactionId","occurredAt","status","amount"],"properties":{"transactionId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"userId":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string","enum":["settled","pending","failed","refunded","chargeback"]},"amount":{"oneOf":[{"type":"number","minimum":0,"examples":[0.018]},{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d+)?$","examples":["0.018"]}],"description":"Non-negative monetary amount in the record currency. Send either a JSON number or a canonical decimal string without exponent notation; the service calculates with Decimal arithmetic."},"feeAmount":{"oneOf":[{"type":"number","minimum":0,"examples":[0.018]},{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d+)?$","examples":["0.018"]}],"description":"Non-negative monetary amount in the record currency. Send either a JSON number or a canonical decimal string without exponent notation; the service calculates with Decimal arithmetic."},"refundAmount":{"oneOf":[{"type":"number","minimum":0,"examples":[0.018]},{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d+)?$","examples":["0.018"]}],"description":"Non-negative monetary amount in the record currency. Send either a JSON number or a canonical decimal string without exponent notation; the service calculates with Decimal arithmetic."},"creditedAmount":{"oneOf":[{"type":"number","minimum":0,"examples":[0.018]},{"type":"string","pattern":"^(?:0|[1-9]\\d*)(?:\\.\\d+)?$","examples":["0.018"]}],"description":"Non-negative monetary amount in the record currency. Send either a JSON number or a canonical decimal string without exponent notation; the service calculates with Decimal arithmetic."},"currency":{"type":"string","examples":["USD"]}}}}}},"ConnectorPayload":{"type":"object","additionalProperties":false,"required":["connector","logs"],"properties":{"connector":{"type":"string","enum":["new-api","one-api","one-hub","voapi"]},"currency":{"type":"string","default":"USD"},"quotaPerUnit":{"type":"number","exclusiveMinimum":0,"description":"Required when native logs contain quota but no monetary amount. Read the deployed value from /api/status.data.quota_per_unit; no global default is assumed."},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"logs":{"description":"Native log array or native paginated API response."},"channels":{"description":"Optional native channel response; credential fields are rejected."},"upstreamCharges":{"description":"Optional native or canonical upstream billing records."},"payments":{"description":"Optional payment settlement records."}}},"ConnectorCatalogMeta":{"type":"object","additionalProperties":false,"required":["count","manifestVersion","hostedRemotePull","credentialStorage","credentialsAccepted","executableManifests","promptContentRead"],"properties":{"count":{"type":"integer","minimum":0},"manifestVersion":{"type":"string"},"hostedRemotePull":{"type":"boolean","const":false},"credentialStorage":{"type":"boolean","const":false},"credentialsAccepted":{"type":"boolean","const":false},"executableManifests":{"type":"boolean","const":false},"promptContentRead":{"type":"boolean","const":false}}},"ConnectorManifest":{"type":"object","additionalProperties":false,"required":["manifestVersion","connector","security","ingress","source","capabilities","normalization"],"properties":{"manifestVersion":{"type":"string","description":"Version of this data-only manifest contract."},"connector":{"type":"object","additionalProperties":false,"required":["id","name","family","maturity","verifiedAt"],"properties":{"id":{"type":"string","enum":["new-api","one-api","one-hub","voapi"]},"name":{"type":"string"},"family":{"type":"string"},"maturity":{"type":"string","enum":["verified","compatible","file-import","planned"]},"verifiedAt":{"type":"string","format":"date"}}},"security":{"$ref":"#/components/schemas/ConnectorSecurityBoundary"},"ingress":{"$ref":"#/components/schemas/ConnectorIngressContract"},"source":{"$ref":"#/components/schemas/ConnectorSourceContract"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorCapability"}},"normalization":{"type":"object","additionalProperties":false,"required":["inputFamily","fieldMap","limitations"],"properties":{"inputFamily":{"type":"string"},"fieldMap":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorFieldMap"}},"limitations":{"type":"array","items":{"type":"string"}}}}}},"ConnectorSecurityBoundary":{"type":"object","additionalProperties":false,"required":["hostedRemotePull","credentialsAccepted","credentialsStored","executableCodeAccepted","promptContentRequired","sourceCredentialsManagedBy","prohibitedFields"],"properties":{"hostedRemotePull":{"type":"boolean","const":false},"credentialsAccepted":{"type":"boolean","const":false},"credentialsStored":{"type":"boolean","const":false},"executableCodeAccepted":{"type":"boolean","const":false},"promptContentRequired":{"type":"boolean","const":false},"sourceCredentialsManagedBy":{"type":"string","const":"caller"},"prohibitedFields":{"type":"array","items":{"type":"string"}}}},"ConnectorIngressContract":{"type":"object","additionalProperties":false,"required":["method","path","mediaType","maxBodyBytes","connectorValue","requiredFields","optionalFields","conditionalRequirements"],"properties":{"method":{"type":"string","const":"POST"},"path":{"type":"string","const":"/api/v1/normalize"},"mediaType":{"type":"string","const":"application/json"},"maxBodyBytes":{"type":"integer","minimum":1},"connectorValue":{"type":"string","enum":["new-api","one-api","one-hub","voapi"]},"requiredFields":{"type":"array","prefixItems":[{"type":"string","const":"connector"},{"type":"string","const":"logs"}],"minItems":2,"maxItems":2},"optionalFields":{"type":"array","items":{"type":"string"}},"conditionalRequirements":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["field","when","sourceHint"],"properties":{"field":{"type":"string","const":"quotaPerUnit"},"when":{"type":"string"},"sourceHint":{"type":"string"}}}}}},"ConnectorSourceContract":{"type":"object","additionalProperties":false,"required":["access","authType","authHeaderNames","resources"],"properties":{"access":{"type":"string","enum":["caller-operated-api","caller-exported-file"]},"authType":{"type":"string"},"authHeaderNames":{"type":"array","description":"Header names only. Manifest responses never contain credential values.","items":{"type":"string"}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorSourceResource"}}}},"ConnectorSourceResource":{"type":"object","additionalProperties":false,"required":["id","label","method","path","permission","scope","notes"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"method":{"type":"string","enum":["GET","POST"]},"path":{"type":"string","description":"Relative source-project path for a caller-operated reader, never a hosted fetch target."},"permission":{"type":"string"},"scope":{"type":"string","const":"caller-operated-source"},"notes":{"type":"string"}}},"ConnectorCapability":{"type":"object","additionalProperties":false,"required":["id","support","ingress","resourceIds","canonicalOutputs","sideEffect","notes"],"properties":{"id":{"type":"string","enum":["usage-log-normalization","upstream-charge-import","payment-settlement-import","channel-metadata-source","top-up-log-source","channel-balance-refresh-source"]},"support":{"type":"string","enum":["verified","supported","compatible","file-only","unavailable"]},"ingress":{"type":"array","items":{"type":"string","enum":["hosted-json-push","local-source-api","local-file"]}},"resourceIds":{"type":"array","items":{"type":"string"}},"canonicalOutputs":{"type":"array","items":{"type":"string","enum":["downstreamUsage","upstreamCharges","payments"]}},"sideEffect":{"type":"boolean"},"notes":{"type":"string"}}},"ConnectorFieldMap":{"type":"object","additionalProperties":false,"required":["source","canonical"],"properties":{"source":{"type":"string"},"canonical":{"type":"string"},"notes":{"type":"string"}}},"ReconciliationReport":{"type":"object","required":["version","generatedAt","currency","summary","findings","byModel","byChannel"],"properties":{"version":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"currency":{"type":"string"},"completeness":{"type":"object","additionalProperties":{"type":"boolean"}},"summary":{"type":"object","additionalProperties":true},"findings":{"type":"array","items":{"type":"object","required":["id","severity","code","message"],"properties":{"id":{"type":"string"},"severity":{"type":"string","enum":["critical","warning","info"]},"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"transactionId":{"type":"string"},"model":{"type":"string"},"channelId":{"type":"string"},"amount":{"type":"number"}}}},"byModel":{"type":"array","items":{"type":"object"}},"byChannel":{"type":"array","items":{"type":"object"}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"InvalidRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"Payload exceeds the 2 MB API limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ConnectorNotFound":{"description":"The connector ID is not supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}