{"openapi":"3.1.1","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"ResolveMesh API","version":"0.1.0","description":"ResolveMesh accepts a sanitized intent, recommends manually approved read-only provider connections, and learns from reported outcomes. ResolveMesh does not proxy provider execution; clients connect to providers directly and keep provider credentials and output outside ResolveMesh."},"servers":[{"url":"https://resolvemesh.com"}],"tags":[{"name":"Resolution","description":"Capability resolution and outcomes."},{"name":"Billing","description":"Stripe-hosted subscription sessions."},{"name":"Demand intelligence","description":"Public, privacy-thresholded unmet demand."},{"name":"Operations","description":"Service health and readiness."}],"paths":{"/v1/resolutions":{"post":{"operationId":"createResolution","summary":"Resolve a missing read-only capability","description":"Submit a sanitized intent and receive ranked provider connections. The caller executes directly with a selected provider.","tags":["Resolution"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolutionRequest"}}}},"responses":{"200":{"description":"Resolution result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolutionResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"413":{"description":"Request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"429":{"description":"A usage or reporting limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/outcomes":{"post":{"operationId":"reportOutcome","summary":"Report the result of a resolved capability","tags":["Resolution"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"description":"A caller-generated key that makes retries safe.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeReport"}}}},"responses":{"200":{"description":"Idempotent replay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeResponse"}}}},"201":{"description":"Outcome recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Request conflicts with existing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"413":{"description":"Request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"429":{"description":"A usage or reporting limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/billing/checkout":{"post":{"operationId":"createCheckoutSession","summary":"Create a Stripe Checkout session","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"description":"A caller-generated key that makes retries safe.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$","minLength":8,"maxLength":128}}],"responses":{"201":{"description":"Checkout session created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSessionResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Request conflicts with existing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/billing/portal":{"post":{"operationId":"createBillingPortalSession","summary":"Create a Stripe customer portal session","tags":["Billing"],"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Portal session created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingSessionResponse"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/gap-clusters":{"get":{"operationId":"listGapClusters","summary":"List public unmet capability demand","description":"Returns privacy-thresholded rolling aggregates when public gap publication is enabled.","tags":["Demand intelligence"],"security":[],"parameters":[{"in":"query","name":"cursor","required":false,"schema":{"type":"string","pattern":"^gap_cursor_[A-Za-z0-9_-]{1,128}$"}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Published gap clusters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GapClusterListResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/v1/gap-clusters/{gapClusterId}":{"get":{"operationId":"getGapCluster","summary":"Get one public gap cluster","tags":["Demand intelligence"],"security":[],"parameters":[{"in":"path","name":"gapClusterId","required":true,"schema":{"type":"string","pattern":"^gap_[0-9a-f]{32}$"}}],"responses":{"200":{"description":"Published gap cluster.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GapCluster"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/healthz":{"get":{"operationId":"getLiveness","summary":"Check process liveness","tags":["Operations"],"security":[],"responses":{"200":{"description":"Service status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/readyz":{"get":{"operationId":"getReadiness","summary":"Check dependency readiness","tags":["Operations"],"security":[],"responses":{"200":{"description":"Service status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessResponse"}}}},"503":{"description":"Dependencies are not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ResolveMesh API key","description":"Use a tenant-scoped rsl_live_ or rsl_test_ API key."}},"schemas":{"ApiErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED","BILLING_CUSTOMER_NOT_FOUND","IDEMPOTENCY_CONFLICT","IDEMPOTENCY_KEY_REQUIRED","INVALID_JSON","NOT_FOUND","OUTCOME_LIMIT_EXCEEDED","PAYLOAD_TOO_LARGE","USAGE_LIMIT_EXCEEDED","SUBSCRIPTION_ALREADY_ACTIVE","VALIDATION_ERROR","INTERNAL_ERROR"]},"message":{"type":"string","minLength":1,"maxLength":500},"retryable":{"type":"boolean"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","retryable","details"],"additionalProperties":false},"requestId":{"type":"string","minLength":1,"maxLength":128}},"required":["error","requestId"],"additionalProperties":false},"BillingSessionResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"],"additionalProperties":false},"GapCluster":{"type":"object","properties":{"category":{"type":"string","enum":["PUBLIC_RECORD_RETRIEVAL","CURRENT_WEB_RESEARCH","DOCUMENT_FACT_EXTRACTION","CODEBASE_ANALYSIS","MEDIA_UNDERSTANDING","STRUCTURED_DATA_LOOKUP","OTHER_READ_ONLY"]},"capabilityType":{"type":"string","enum":["DATA_RETRIEVAL","WEB_SEARCH","DOCUMENT_ANALYSIS","CODE_ANALYSIS","MEDIA_ANALYSIS","OTHER"]},"allowedProtocols":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["MCP","A2A","REST"]}},"requiresCitations":{"type":"boolean"},"latencyBucket":{"type":"string","enum":["UNSPECIFIED","FAST","STANDARD","RELAXED"]},"gapClusterId":{"type":"string","pattern":"^gap_[0-9a-f]{32}$"},"label":{"type":"string","minLength":1,"maxLength":160},"eventCount":{"type":"integer","minimum":20,"maximum":9007199254740991},"distinctTenantCount":{"type":"integer","minimum":5,"maximum":9007199254740991},"firstSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lastSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"trend":{"type":"string","enum":["RISING","STEADY","FALLING"]},"windowDays":{"type":"number","const":30}},"required":["category","capabilityType","allowedProtocols","requiresCitations","latencyBucket","gapClusterId","label","eventCount","distinctTenantCount","firstSeenAt","lastSeenAt","trend","windowDays"],"additionalProperties":false},"GapClusterListResponse":{"type":"object","properties":{"clusters":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"category":{"type":"string","enum":["PUBLIC_RECORD_RETRIEVAL","CURRENT_WEB_RESEARCH","DOCUMENT_FACT_EXTRACTION","CODEBASE_ANALYSIS","MEDIA_UNDERSTANDING","STRUCTURED_DATA_LOOKUP","OTHER_READ_ONLY"]},"capabilityType":{"type":"string","enum":["DATA_RETRIEVAL","WEB_SEARCH","DOCUMENT_ANALYSIS","CODE_ANALYSIS","MEDIA_ANALYSIS","OTHER"]},"allowedProtocols":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["MCP","A2A","REST"]}},"requiresCitations":{"type":"boolean"},"latencyBucket":{"type":"string","enum":["UNSPECIFIED","FAST","STANDARD","RELAXED"]},"gapClusterId":{"type":"string","pattern":"^gap_[0-9a-f]{32}$"},"label":{"type":"string","minLength":1,"maxLength":160},"eventCount":{"type":"integer","minimum":20,"maximum":9007199254740991},"distinctTenantCount":{"type":"integer","minimum":5,"maximum":9007199254740991},"firstSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lastSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"trend":{"type":"string","enum":["RISING","STEADY","FALLING"]},"windowDays":{"type":"number","const":30}},"required":["category","capabilityType","allowedProtocols","requiresCitations","latencyBucket","gapClusterId","label","eventCount","distinctTenantCount","firstSeenAt","lastSeenAt","trend","windowDays"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string","pattern":"^gap_cursor_[A-Za-z0-9_-]{1,128}$"},{"type":"null"}]}},"required":["clusters","nextCursor"],"additionalProperties":false},"OutcomeReport":{"type":"object","properties":{"resolutionId":{"type":"string","minLength":1,"maxLength":128},"capabilityId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["SUCCEEDED","FAILED","ABANDONED"]},"durationMs":{"type":"integer","minimum":0,"maximum":86400000},"failureCode":{"anyOf":[{"type":"string","enum":["AUTH_UNAVAILABLE","CAPABILITY_MISMATCH","INVALID_PARAMETERS","PROVIDER_UNAVAILABLE","TIMEOUT","INCORRECT_RESULT","UNVERIFIABLE_RESULT","UNKNOWN"]},{"type":"null"}]}},"required":["resolutionId","capabilityId","status","durationMs","failureCode"],"additionalProperties":false},"OutcomeResponse":{"type":"object","properties":{"outcomeId":{"type":"string","minLength":1,"maxLength":128},"resolutionId":{"type":"string","minLength":1,"maxLength":128},"capabilityId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["SUCCEEDED","FAILED","ABANDONED"]},"recordedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["outcomeId","resolutionId","capabilityId","status","recordedAt"],"additionalProperties":false},"ResolutionRequest":{"type":"object","properties":{"intentText":{"type":"string","minLength":1,"maxLength":500},"capabilityTypes":{"minItems":1,"type":"array","items":{"type":"string","enum":["DATA_RETRIEVAL","WEB_SEARCH","DOCUMENT_ANALYSIS","CODE_ANALYSIS","MEDIA_ANALYSIS","OTHER"]}},"allowedProtocols":{"minItems":1,"type":"array","items":{"type":"string","enum":["MCP","A2A","REST"]}},"riskClass":{"type":"string","const":"READ_ONLY"},"constraints":{"type":"object","properties":{"requiresCitations":{"type":"boolean"},"maxLatencyMs":{"type":"integer","exclusiveMinimum":0,"maximum":120000}},"additionalProperties":false}},"required":["intentText","capabilityTypes","allowedProtocols","riskClass"],"additionalProperties":false},"ResolutionResponse":{"type":"object","properties":{"resolutionId":{"type":"string","minLength":1,"maxLength":128},"status":{"type":"string","enum":["MATCHED","AMBIGUOUS","UNRESOLVED"]},"matches":{"type":"array","items":{"type":"object","properties":{"capabilityId":{"type":"string","minLength":1,"maxLength":128},"providerId":{"type":"string","minLength":1,"maxLength":128},"protocol":{"type":"string","enum":["MCP","A2A","REST"]},"confidence":{"type":"number","minimum":0,"maximum":1},"scoreBreakdown":{"type":"object","properties":{"semanticMatch":{"type":"number","minimum":0,"maximum":1},"availability":{"type":"number","minimum":0,"maximum":1},"freshness":{"type":"number","minimum":0,"maximum":1},"observedSuccess":{"type":"number","minimum":0,"maximum":1},"authCompatibility":{"type":"number","minimum":0,"maximum":1},"costLatencyFit":{"type":"number","minimum":0,"maximum":1}},"required":["semanticMatch","availability","freshness","observedSuccess","authCompatibility","costLatencyFit"],"additionalProperties":false},"connection":{"type":"object","properties":{"endpoint":{"type":"string","format":"uri"}},"required":["endpoint"],"additionalProperties":false},"evidence":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"CAPABILITY_VERIFICATION"},"verifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["type","verifiedAt"],"additionalProperties":false}}},"required":["capabilityId","providerId","protocol","confidence","scoreBreakdown","connection","evidence"],"additionalProperties":false}}},"required":["resolutionId","status","matches"],"additionalProperties":false},"HealthResponse":{"type":"object","additionalProperties":false,"properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]},"ReadinessResponse":{"type":"object","additionalProperties":false,"properties":{"status":{"type":"string","enum":["ready","not_ready"]}},"required":["status"]}}}}