{"openapi":"3.1.0","info":{"title":"AgentRouter API","version":"1.0.0"},"paths":{"/domains":{"get":{"operationId":"list-domains","summary":"List supported domains","tags":["catalog"],"responses":{"200":{"description":"Supported AgentRouter domains","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DomainCatalogEntry"}}}}}}}},"/domains/{domainKey}":{"get":{"operationId":"get-domain","summary":"Get one domain","tags":["catalog"],"parameters":[{"name":"domainKey","in":"path","description":"Domain identifier such as email, search, text, web, enrichment, or social.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"One supported domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainCatalogEntry"}}}},"404":{"description":"Requested resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/domains/{domainKey}/capabilities":{"get":{"operationId":"list-capabilities","summary":"List capabilities for one domain","tags":["catalog"],"parameters":[{"name":"domainKey","in":"path","description":"Domain identifier such as email, search, text, web, enrichment, or social.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Capabilities inside the selected domain","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CapabilityCatalogEntry"}}}}},"404":{"description":"Requested resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/domains/{domainKey}/capabilities/{capabilityId}":{"get":{"operationId":"get-capability","summary":"Get one capability","tags":["catalog"],"parameters":[{"name":"domainKey","in":"path","description":"Domain identifier such as email, search, text, web, enrichment, or social.","required":true,"schema":{"type":"string"}},{"name":"capabilityId","in":"path","description":"Capability identifier inside the selected domain, such as send, answer, analyze, people-search, or extract.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"One capability entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilityCatalogEntry"}}}},"404":{"description":"Requested resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/domains/{domainKey}/routes":{"get":{"operationId":"list-domain-routes","summary":"List routes for one domain","tags":["catalog"],"parameters":[{"name":"domainKey","in":"path","description":"Domain identifier such as email, search, text, web, enrichment, or social.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Provider routes inside the selected domain","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RouteCatalogEntry"}}}}},"404":{"description":"Requested resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/domains/{domainKey}/capabilities/{capabilityId}/routes":{"get":{"operationId":"list-capability-routes","summary":"List routes for one capability","tags":["catalog"],"parameters":[{"name":"domainKey","in":"path","description":"Domain identifier such as email, search, text, web, enrichment, or social.","required":true,"schema":{"type":"string"}},{"name":"capabilityId","in":"path","description":"Capability identifier inside the selected domain, such as send, answer, analyze, people-search, or extract.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Provider routes for the selected capability","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RouteCatalogEntry"}}}}},"404":{"description":"Requested resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/domains/{domainKey}/capabilities/{capabilityId}/contract":{"get":{"operationId":"get-capability-contract","summary":"Get the field-level contract for one capability","tags":["contracts"],"parameters":[{"name":"domainKey","in":"path","description":"Domain identifier such as email, search, text, web, enrichment, or social.","required":true,"schema":{"type":"string"}},{"name":"capabilityId","in":"path","description":"Capability identifier inside the selected domain, such as send, answer, analyze, people-search, or extract.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Capability contract for recommend and execute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilityContract"}}}},"404":{"description":"Requested resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/domains/{domainKey}/capabilities/{capabilityId}/recommend":{"post":{"operationId":"recommend-capability-route","summary":"Recommend the best route for a capability","tags":["routing"],"parameters":[{"name":"domainKey","in":"path","description":"Domain identifier such as email, search, text, web, enrichment, or social.","required":true,"schema":{"type":"string"}},{"name":"capabilityId","in":"path","description":"Capability identifier inside the selected domain, such as send, answer, analyze, people-search, or extract.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Route recommendation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationResponse"}}}},"401":{"description":"Missing or invalid AgentRouter API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilityInput"}}}}}},"/domains/{domainKey}/capabilities/{capabilityId}/execute":{"post":{"operationId":"execute-capability","summary":"Execute one capability","tags":["routing"],"parameters":[{"name":"domainKey","in":"path","description":"Domain identifier such as email, search, text, web, enrichment, or social.","required":true,"schema":{"type":"string"}},{"name":"capabilityId","in":"path","description":"Capability identifier inside the selected domain, such as send, answer, analyze, people-search, or extract.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Capability execution result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericExecutionResponse"}}}},"401":{"description":"Missing or invalid AgentRouter API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilityInput"}}}}}},"/wallet":{"get":{"operationId":"get-wallet","summary":"Read wallet balance","tags":["wallet"],"parameters":[{"name":"userId","in":"query","description":"Optional user override in supported environments.","required":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Wallet balance in credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletResponse"}}}},"401":{"description":"Missing or invalid AgentRouter API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/usage":{"get":{"operationId":"get-usage","summary":"List recent usage","tags":["usage"],"parameters":[{"name":"limit","in":"query","description":"Maximum number of recent usage items to return.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"Authorization","in":"header","description":"Bearer authentication","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recent usage for the current AgentRouter user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Missing or invalid AgentRouter API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/dev/init":{"post":{"operationId":"dev-init","summary":"Initialize non-production development state","description":"Non-production helper for local testing.","tags":["development"],"responses":{"200":{"description":"Initialized development wallet and provider context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevInitResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevInitRequest"}}}}}}},"servers":[{"url":"https://api.agentrouter.to/api/agentic-api","description":"Hosted AgentRouter API"}],"components":{"schemas":{"DomainCatalogEntryStatus":{"type":"string","enum":["live","pending"],"title":"DomainCatalogEntryStatus"},"DomainCatalogEntry":{"type":"object","properties":{"domainKey":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"status":{"$ref":"#/components/schemas/DomainCatalogEntryStatus"},"capabilitiesPath":{"type":"string"},"routesPath":{"type":"string"},"routeEndpoint":{"type":["string","null"]},"supportsIntentRouting":{"type":"boolean"},"liveCapabilityCount":{"type":"integer"},"totalCapabilityCount":{"type":"integer"},"startingPriceCredits":{"type":"integer"}},"required":["domainKey","label","description","status","capabilitiesPath","routesPath","routeEndpoint","supportsIntentRouting","liveCapabilityCount","totalCapabilityCount"],"title":"DomainCatalogEntry"},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}},"title":"ErrorResponse"},"CapabilityCatalogEntryStatus":{"type":"string","enum":["live","recommend_only","planned","pending"],"title":"CapabilityCatalogEntryStatus"},"CapabilityCatalogEntryAvailableRouteModesItems":{"type":"string","enum":["managed","byo","redirect"],"title":"CapabilityCatalogEntryAvailableRouteModesItems"},"CapabilityCatalogEntryContractStatus":{"type":"string","enum":["available","partial","unavailable"],"title":"CapabilityCatalogEntryContractStatus"},"CapabilityCatalogEntry":{"type":"object","properties":{"capabilityKey":{"type":"string"},"capabilityId":{"type":"string"},"domainKey":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"status":{"$ref":"#/components/schemas/CapabilityCatalogEntryStatus"},"supportedProviders":{"type":"array","items":{"type":"string"}},"enabledProviders":{"type":"array","items":{"type":"string"}},"supportedFeatures":{"type":"array","items":{"type":"string"}},"availableRouteModes":{"type":"array","items":{"$ref":"#/components/schemas/CapabilityCatalogEntryAvailableRouteModesItems"}},"startingPriceCredits":{"type":"number","format":"double"},"recommendEndpoint":{"type":"string"},"executeEndpoint":{"type":"string"},"routesEndpoint":{"type":["string","null"]},"docsUrl":{"type":"string","format":"uri"},"contractEndpoint":{"type":"string"},"contractStatus":{"$ref":"#/components/schemas/CapabilityCatalogEntryContractStatus"}},"required":["capabilityKey","capabilityId","domainKey","label","description","status","supportedProviders","enabledProviders","supportedFeatures","availableRouteModes","routesEndpoint","contractStatus"],"title":"CapabilityCatalogEntry"},"RouteCatalogEntryNetworkKey":{"type":"string","enum":["direct","agentcash","mpp"],"title":"RouteCatalogEntryNetworkKey"},"RouteCatalogEntryRouteMode":{"type":"string","enum":["managed","byo","redirect"],"title":"RouteCatalogEntryRouteMode"},"RouteCatalogEntryStatus":{"type":"string","enum":["live","pending"],"title":"RouteCatalogEntryStatus"},"RouteCatalogEntry":{"type":"object","properties":{"routeKey":{"type":"string"},"domainKey":{"type":"string"},"capabilityKey":{"type":"string"},"capabilityId":{"type":"string"},"providerKey":{"type":"string"},"providerLabel":{"type":"string"},"networkKey":{"$ref":"#/components/schemas/RouteCatalogEntryNetworkKey"},"routeMode":{"$ref":"#/components/schemas/RouteCatalogEntryRouteMode"},"managedByAgenticApi":{"type":"boolean"},"settlementRail":{"type":"string"},"supportedFeatures":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"startingCostCredits":{"type":"number","format":"double"},"status":{"$ref":"#/components/schemas/RouteCatalogEntryStatus"}},"required":["routeKey","domainKey","capabilityKey","capabilityId","providerKey","providerLabel","networkKey","routeMode","managedByAgenticApi","supportedFeatures","summary","startingCostCredits","status"],"title":"RouteCatalogEntry"},"CapabilityContractContractStatus":{"type":"string","enum":["available","partial","unavailable"],"title":"CapabilityContractContractStatus"},"CapabilityOperationContractStatus":{"type":"string","enum":["available","partial","unavailable"],"title":"CapabilityOperationContractStatus"},"CapabilityFieldContractType":{"type":"string","enum":["string","number","integer","boolean","array","object","unknown"],"title":"CapabilityFieldContractType"},"CapabilityFieldContract":{"type":"object","properties":{"name":{"type":"string"},"type":{"$ref":"#/components/schemas/CapabilityFieldContractType"},"required":{"type":"boolean"},"conditionallyRequired":{"type":"boolean"},"enumValues":{"type":"array","items":{"type":"string"}},"maxLength":{"type":"integer"},"min":{"type":"number","format":"double"},"max":{"type":"number","format":"double"},"itemsType":{"type":"string"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/CapabilityFieldContract"}},"notes":{"type":"array","items":{"type":"string"}}},"required":["name","type","required"],"title":"CapabilityFieldContract"},"CapabilityInput":{"type":"object","additionalProperties":{"description":"Any type"},"description":"Capability-specific request body. Use the contract endpoint for exact fields.","title":"CapabilityInput"},"CapabilityOperationContract":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/CapabilityOperationContractStatus"},"dtoName":{"type":"string"},"requiredFields":{"type":"array","items":{"type":"string"}},"optionalFields":{"type":"array","items":{"type":"string"}},"conditionallyRequiredFields":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/CapabilityFieldContract"}},"requestExample":{"$ref":"#/components/schemas/CapabilityInput"},"responseExample":{"type":"object","additionalProperties":{"description":"Any type"}},"notes":{"type":"array","items":{"type":"string"}}},"required":["status","requiredFields","optionalFields","conditionallyRequiredFields","fields","notes"],"title":"CapabilityOperationContract"},"CapabilityContract":{"type":"object","properties":{"domainKey":{"type":"string"},"capabilityKey":{"type":"string"},"capabilityId":{"type":"string"},"docsUrl":{"type":"string","format":"uri"},"contractStatus":{"$ref":"#/components/schemas/CapabilityContractContractStatus"},"recommend":{"$ref":"#/components/schemas/CapabilityOperationContract"},"execute":{"$ref":"#/components/schemas/CapabilityOperationContract"},"notes":{"type":"array","items":{"type":"string"}}},"required":["domainKey","capabilityKey","capabilityId","contractStatus","notes"],"title":"CapabilityContract"},"RecommendationResponseRecommendedRouteMode":{"type":"string","enum":["managed","byo","redirect"],"title":"RecommendationResponseRecommendedRouteMode"},"WorkflowRecommendation":{"type":"object","properties":{"workflowType":{"type":"string"},"summary":{"type":"string"},"managedAfterAcquisition":{"type":"boolean"},"acquisitionCapabilityKey":{"type":"string"},"acquisitionRouteKey":{"type":"string"},"acquisitionProvider":{"type":"string"},"acquisitionPriceCredits":{"type":"number","format":"double"},"executeRouteKey":{"type":"string"},"executeProvider":{"type":"string"},"executePriceCredits":{"type":"number","format":"double"},"estimatedFirstExecutionTotalCredits":{"type":"number","format":"double"},"recurringExecutionCredits":{"type":"number","format":"double"},"blockingRequirements":{"type":"array","items":{"type":"string"}},"nextActions":{"type":"array","items":{"type":"string"}},"reasons":{"type":"array","items":{"type":"string"}}},"required":["workflowType","summary","blockingRequirements","nextActions","reasons"],"title":"WorkflowRecommendation"},"RecommendationCandidateRouteMode":{"type":"string","enum":["managed","byo","redirect"],"title":"RecommendationCandidateRouteMode"},"RecommendationCandidate":{"type":"object","properties":{"provider":{"type":"string"},"routeKey":{"type":"string"},"routeMode":{"$ref":"#/components/schemas/RecommendationCandidateRouteMode"},"canExecuteNow":{"type":"boolean"},"score":{"type":"number","format":"double"},"priceCredits":{"type":"number","format":"double"},"trackingSupported":{"type":"boolean"},"supportedFeatures":{"type":"array","items":{"type":"string"}},"settlementRail":{"type":"string"},"blockingRequirements":{"type":"array","items":{"type":"string"}},"nextActions":{"type":"array","items":{"type":"string"}},"reasons":{"type":"array","items":{"type":"string"}}},"required":["provider","routeKey","routeMode","canExecuteNow","score","priceCredits","supportedFeatures","blockingRequirements","nextActions","reasons"],"title":"RecommendationCandidate"},"RecommendationResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"productKey":{"type":"string"},"preferenceSource":{"type":"string"},"optimizationPreferences":{"type":"array","items":{"type":"string"}},"recommendedProvider":{"type":"string"},"recommendedRouteKey":{"type":"string"},"recommendedRouteMode":{"$ref":"#/components/schemas/RecommendationResponseRecommendedRouteMode"},"canExecuteNow":{"type":"boolean"},"bestExecutableProvider":{"type":"string"},"bestExecutableRouteKey":{"type":"string"},"bestExecutableRouteMode":{"type":"string"},"bestWorkflowRecommendation":{"$ref":"#/components/schemas/WorkflowRecommendation"},"blockingRequirements":{"type":"array","items":{"type":"string"}},"nextActions":{"type":"array","items":{"type":"string"}},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/RecommendationCandidate"}},"workflowRecommendations":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRecommendation"}}},"required":["success","recommendedProvider","recommendedRouteKey","recommendedRouteMode","canExecuteNow","blockingRequirements","nextActions","candidates","workflowRecommendations"],"title":"RecommendationResponse"},"GenericExecutionResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"status":{"type":"string"},"provider":{"type":"string"},"routeKey":{"type":"string"},"creditsCharged":{"type":"number","format":"double"},"providerMessageId":{"type":"string"},"data":{"type":"object","additionalProperties":{"description":"Any type"}}},"required":["success"],"title":"GenericExecutionResponse"},"WalletResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"userId":{"type":"string"},"balanceCredits":{"type":"integer"}},"required":["success","userId","balanceCredits"],"title":"WalletResponse"},"UsageResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"userId":{"type":"string"},"items":{"type":"array","items":{"type":"object","additionalProperties":{"description":"Any type"}}}},"required":["success","userId","items"],"title":"UsageResponse"},"DevInitRequest":{"type":"object","properties":{"userId":{"type":"string"},"balanceCredits":{"type":"integer","minimum":1}},"title":"DevInitRequest"},"DevInitResponseProductsItems":{"type":"object","properties":{"productKey":{"type":"string"},"startingPrice":{"type":"number","format":"double"}},"required":["productKey","startingPrice"],"title":"DevInitResponseProductsItems"},"DevInitResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"userId":{"type":"string"},"balanceCredits":{"type":"integer"},"credited":{"type":"integer"},"providers":{"type":"array","items":{"type":"string"}},"enabledProviders":{"type":"array","items":{"type":"string"}},"products":{"type":"array","items":{"$ref":"#/components/schemas/DevInitResponseProductsItems"}}},"required":["success","userId","balanceCredits","credited","providers","enabledProviders","products"],"title":"DevInitResponse"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}