{ "openapi": "3.1.1", "info": { "title": "NewsletterIdea API", "description": "NewsletterIdea API exposes AI-powered newsletter opportunity intelligence, managed-agent runs, validated findings artifacts, commerce operations, usage telemetry, and developer onboarding contracts. The API is generated from the running ASP.NET Core endpoint graph and published as OpenAPI 3.1 for strongly typed SDK generation.", "termsOfService": "https://newsletteridea.com/terms", "contact": { "name": "NewsletterIdea API Support", "url": "https://newsletteridea.com/contact", "email": "support@newsletteridea.com" }, "version": "v1", "summary": "Production API for newsletter opportunity intelligence." }, "servers": [ { "url": "https://newsletteridea.com", "description": "Production" } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Check public API health", "description": "Returns the public service health contract, API version, findings schema version, hosting contract validation, and managed-agent provisioning drift status.", "responses": { "200": { "description": "OK" }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/health/ready": { "get": { "tags": [ "Health" ], "responses": { "200": { "description": "OK" }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/checkout/start": { "post": { "tags": [ "Checkout" ], "operationId": "StartBrowserCheckout", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BrowserCheckoutForm" } } }, "required": true }, "responses": { "302": { "description": "Found" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/scan": { "post": { "tags": [ "Free Scan" ], "summary": "Request a free newsletter idea scan", "description": "Accepts an email address and newsletter idea, validates confirmation-token safety, and queues a free scan workflow when email delivery is configured.", "operationId": "CreateFreeScan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeScanRequestDto" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeScanAcceptedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "description": "Payload Too Large", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/scan/confirm": { "get": { "tags": [ "Free Scan" ], "summary": "Confirm a free scan request", "description": "Verifies the protected confirmation token, records the consent timestamp, and returns the confirmed scan metadata.", "operationId": "ConfirmFreeScan", "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeScanConfirmedDto" } } } }, "302": { "description": "Found" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/scan/status": { "post": { "tags": [ "v1" ], "operationId": "LookupFreeScanStatus", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeScanStatusLookupDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeScanStatusLookupResultDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/marketing/unsubscribe": { "get": { "tags": [ "v1" ], "operationId": "UnsubscribeMarketing", "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Found" }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/auth/sign-in-link": { "post": { "tags": [ "Authentication" ], "summary": "Send a passwordless sign-in link", "description": "Accepts an email address, creates the customer account when needed, and sends a short-lived one-time transactional sign-in link. The response is deliberately generic to avoid account enumeration.", "operationId": "CreateSignInLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInLinkRequestDto" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInLinkAcceptedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/auth/password-reset-link": { "post": { "tags": [ "Authentication" ], "summary": "Send a password-reset link", "description": "Accepts an email address and returns the same generic response for known and unknown accounts. Active accounts receive a short-lived, one-time transactional password-reset link.", "operationId": "CreatePasswordResetLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetLinkRequestDto" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetLinkAcceptedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/auth/password-reset": { "post": { "tags": [ "Authentication" ], "summary": "Complete a password reset", "description": "Consumes a protected one-time reset token, enforces the server password policy, replaces the password hash, clears lockout state, invalidates outstanding account links, and sends a security notification.", "operationId": "CompletePasswordReset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetCompleteDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordResetCompletedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/support-requests": { "post": { "tags": [ "v1" ], "operationId": "CreateSupportRequest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportRequestDto" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportRequestAcceptedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/evaluations": { "post": { "tags": [ "Runs" ], "summary": "Start a paid idea check", "description": "Consumes one unused Idea Check entitlement owned by the API-key account and starts a durable managed-agent evaluation. The operation is idempotent for the same API-key account, Idempotency-Key, and request body. Requires evaluations:create and a live API key.", "operationId": "CreateEvaluation", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A caller-generated idempotency key for this logical mutation. Reuse the same value only when retrying the same request body after a transport failure.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationCreateDto" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidProductRunCreatedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/searches": { "post": { "tags": [ "Runs" ], "summary": "Start a paid custom search", "description": "Consumes one unused Custom Search entitlement owned by the API-key account and starts a durable managed-agent search that produces validated findings, a dossier, and a ranked portfolio. The operation is idempotent for the same API-key account, Idempotency-Key, and request body. Requires searches:create and a live API key.", "operationId": "CreateSearch", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A caller-generated idempotency key for this logical mutation. Reuse the same value only when retrying the same request body after a transport failure.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCreateDto" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidProductRunCreatedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/opportunities": { "get": { "tags": [ "Opportunities" ], "summary": "List available opportunities", "description": "Returns public opportunity teasers that can be inspected before purchase. Purchased dossiers and internal findings are never returned by this endpoint.", "operationId": "ListOpportunities", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunityTeaserDto" } } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/runs/{id}": { "get": { "tags": [ "Runs" ], "summary": "Get run status", "description": "Returns the current status, provider identifiers, timestamps, cost, and failure reason for a managed-agent run owned by the caller.", "operationId": "GetRun", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStatusDto" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/runs/{id}/findings": { "get": { "tags": [ "Runs" ], "summary": "Download validated findings JSON", "description": "Returns the schema-valid public findings artifact for a completed run. The response is no-store so generated intelligence is not cached by shared infrastructure.", "operationId": "GetRunFindings", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/runs/{id}/dossier": { "get": { "tags": [ "Reports" ], "summary": "Download a run dossier", "description": "Returns a rendered dossier for a completed run. Use the format query parameter to choose HTML or PDF where available.", "operationId": "GetRunDossier", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string" } } ], "responses": { "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/runs/{id}/portfolio": { "get": { "tags": [ "Reports" ], "summary": "Download a custom-search portfolio", "description": "Returns the validated ranked portfolio JSON for a completed Custom Search run owned by the caller. Idea Check runs do not have a portfolio.", "operationId": "GetRunPortfolio", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/opportunities/{id}/dossier": { "get": { "tags": [ "Reports" ], "summary": "Download a purchased catalog dossier", "description": "Returns a purchased catalog opportunity as HTML, PDF, or canonical findings JSON after checking the caller account and dossiers:read scope.", "operationId": "GetPurchasedOpportunityDossier", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Get account profile", "description": "Returns account-level API metadata and fails closed when the account store is not configured.", "operationId": "GetAccount", "responses": { "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Get usage dashboard", "description": "Returns authenticated usage, budget, rate-limit, and cost telemetry for the API key making the request.", "operationId": "GetUsage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageDashboardDto" } } } }, "401": { "description": "Unauthorized" }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/endpoint-catalog": { "get": { "tags": [ "Developer" ], "summary": "List endpoint catalogue", "description": "Returns the machine-readable API endpoint catalogue with audience, scope, idempotency, async-run, and response-scope metadata.", "operationId": "ListEndpointCatalogue", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiEndpointDescriptorDto" } } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/developer": { "get": { "tags": [ "Developer" ], "summary": "Get developer portal metadata", "description": "Returns documentation links, SDK readiness, authentication guidance, and operational API metadata for developer onboarding.", "operationId": "GetDeveloperPortal", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperPortalDto" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/findings-schema": { "get": { "tags": [ "Developer" ], "summary": "Download findings JSON schema", "description": "Returns the canonical JSON Schema for public findings artifacts so API clients can validate run output before ingestion.", "operationId": "GetFindingsJsonSchema", "responses": { "200": { "description": "OK" }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } } } }, "/v1/withdrawals": { "post": { "tags": [ "Withdrawals" ], "summary": "Create a withdrawal request", "description": "Creates an idempotent withdrawal request for a contributor payout and fails closed when payout processing is unavailable.", "operationId": "CreateWithdrawal", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A caller-generated idempotency key for this logical mutation. Reuse the same value only when retrying the same request body after a transport failure.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalCreateDto" } } }, "required": true }, "responses": { "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/withdrawals/{id}": { "get": { "tags": [ "Withdrawals" ], "summary": "Get withdrawal request", "description": "Returns the status and metadata for a withdrawal request owned by the caller.", "operationId": "GetWithdrawal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Lists configured webhook endpoints for the caller once webhook management backing services are available.", "operationId": "ListWebhooks", "responses": { "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "description": "Creates an idempotent webhook endpoint subscription for asynchronous platform events once webhook management backing services are available.", "operationId": "CreateWebhook", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A caller-generated idempotency key for this logical mutation. Reuse the same value only when retrying the same request body after a transport failure.", "required": true, "schema": { "type": "string" } } ], "responses": { "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/checkout-sessions": { "post": { "tags": [ "Commerce" ], "summary": "Create a hosted Stripe Checkout Session", "description": "Authenticates a customer API key, validates its purchases:create scope and test/live mode, records the immutable server-owned product, price, idempotency key, and digital-delivery consent, then returns a Stripe-hosted Checkout URL.", "operationId": "CreateCheckoutSession", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "A caller-generated idempotency key for this logical mutation. Reuse the same value only when retrying the same request body after a transport failure.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionCreateDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionCreatedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } }, "/v1/opportunities/{id}/purchase": { "post": { "tags": [ "Commerce" ], "summary": "Reserve and purchase an opportunity dossier", "description": "Atomically reserves the specified catalog opportunity, creates an idempotent Stripe-hosted Checkout Session, and finalizes exclusivity only after a signed paid webhook reconciles to the order. Late payments are automatically refunded.", "operationId": "PurchaseOpportunity", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "A caller-generated idempotency key for this logical mutation. Reuse the same value only when retrying the same request body after a transport failure.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityPurchaseDto" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionCreatedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The caller exceeded a platform, tenant, or endpoint rate limit.", "content": { "application/problem+json": { } } }, "500": { "description": "An unexpected server-side failure occurred and was logged for administrator review.", "content": { "application/problem+json": { } } } }, "security": [ { "ApiKeyAuth": [ ] } ] } } }, "components": { "schemas": { "ApiEndpointDescriptorDto": { "required": [ "method", "path", "audience", "requiredScope", "requiresIdempotencyKey", "startsAsyncManagedAgentRun", "responseScope" ], "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "audience": { "type": "string" }, "requiredScope": { "type": [ "null", "string" ] }, "requiresIdempotencyKey": { "type": "boolean" }, "startsAsyncManagedAgentRun": { "type": "boolean" }, "responseScope": { "type": [ "null", "string" ] } } }, "BrowserCheckoutForm": { "type": "object", "properties": { "product": { "type": "string" }, "opportunityId": { "type": [ "null", "string" ] }, "idempotencyKey": { "type": "string" }, "immediateAccessConsent": { "type": "boolean" }, "withdrawalLossAcknowledgment": { "type": "boolean" } } }, "CheckoutSessionCreatedDto": { "required": [ "orderId", "status", "checkoutUrl", "checkoutSessionId", "replayed" ], "type": "object", "properties": { "orderId": { "type": "string" }, "status": { "type": "string" }, "checkoutUrl": { "type": [ "null", "string" ] }, "checkoutSessionId": { "type": [ "null", "string" ] }, "replayed": { "type": "boolean" } } }, "CheckoutSessionCreateDto": { "required": [ "product", "opportunityId", "immediateAccessConsent", "withdrawalLossAcknowledgment" ], "type": "object", "properties": { "product": { "type": "string" }, "opportunityId": { "type": [ "null", "string" ] }, "immediateAccessConsent": { "type": "boolean" }, "withdrawalLossAcknowledgment": { "type": "boolean" } } }, "DeveloperPortalApiKeyDto": { "required": [ "hashAlgorithm", "rotationSupported", "revocationSupported", "scopes", "plans" ], "type": "object", "properties": { "hashAlgorithm": { "type": "string" }, "rotationSupported": { "type": "boolean" }, "revocationSupported": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "plans": { "type": "array", "items": { "type": "string" } } } }, "DeveloperPortalDto": { "required": [ "findingsSchemaUrl", "findingsJsonSchemaUrl", "endpointCatalogueUrl", "apiKeyManagement", "usageDashboardUrl", "webhookConfigurationUrl", "sandbox", "codeSamples" ], "type": "object", "properties": { "findingsSchemaUrl": { "type": "string" }, "findingsJsonSchemaUrl": { "type": "string" }, "endpointCatalogueUrl": { "type": "string" }, "apiKeyManagement": { "$ref": "#/components/schemas/DeveloperPortalApiKeyDto" }, "usageDashboardUrl": { "type": "string" }, "webhookConfigurationUrl": { "type": "string" }, "sandbox": { "$ref": "#/components/schemas/DeveloperPortalSandboxDto" }, "codeSamples": { "type": "array", "items": { "type": "string" } } } }, "DeveloperPortalSandboxDto": { "required": [ "testKeyPrefix", "sampleFindingsUrl", "computeSpendUsd" ], "type": "object", "properties": { "testKeyPrefix": { "type": "string" }, "sampleFindingsUrl": { "type": "string" }, "computeSpendUsd": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } } }, "EvaluationCreateDto": { "required": [ "idea", "audience", "geography", "goal", "constraints" ], "type": "object", "properties": { "idea": { "type": [ "null", "string" ] }, "audience": { "type": [ "null", "string" ] }, "geography": { "type": [ "null", "string" ] }, "goal": { "type": [ "null", "string" ] }, "constraints": { "type": [ "null", "array" ], "items": { "type": "string" } }, "consentToSeedCatalog": { "type": "boolean", "default": false }, "orderId": { "type": [ "null", "string" ], "format": "uuid" } } }, "FreeAuditFindingDto": { "required": [ "dimension", "assessment", "evidenceSummary", "sourceIds" ], "type": "object", "properties": { "dimension": { "type": "string" }, "assessment": { "type": "string" }, "evidenceSummary": { "type": "string" }, "sourceIds": { "type": "array", "items": { "type": "string" } } } }, "FreeAuditSourceDto": { "required": [ "sourceId", "title", "url", "publisher", "publishedAt" ], "type": "object", "properties": { "sourceId": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "publishedAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "FreeScanAcceptedDto": { "required": [ "status", "message", "confirmationRequired", "privacyClass", "processingBoundary", "subprocessorDisclosure", "subprocessorDisclosureVersion", "managedAgentSessionCreated", "managedAgentConsentRequired", "developmentConfirmationUrl" ], "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "confirmationRequired": { "type": "boolean" }, "privacyClass": { "type": "string" }, "processingBoundary": { "type": "string" }, "subprocessorDisclosure": { "type": "string" }, "subprocessorDisclosureVersion": { "type": "string" }, "managedAgentSessionCreated": { "type": "boolean" }, "managedAgentConsentRequired": { "type": "boolean" }, "developmentConfirmationUrl": { "type": [ "null", "string" ] } } }, "FreeScanConfirmedDto": { "required": [ "status", "score", "verdictBand", "confidence", "summary", "findings", "risks", "nextSteps", "sources", "isNonExclusive", "isNonAdvisory", "privacyClass", "processingBoundary", "subprocessorDisclosure", "subprocessorDisclosureVersion", "managedAgentSessionCreated", "managedAgentConsentRequired", "eligibleForManagedAgentScan" ], "type": "object", "properties": { "status": { "type": "string" }, "score": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "verdictBand": { "type": [ "null", "string" ] }, "confidence": { "type": [ "null", "string" ] }, "summary": { "type": [ "null", "string" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FreeAuditFindingDto" } }, "risks": { "type": "array", "items": { "type": "string" } }, "nextSteps": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/FreeAuditSourceDto" } }, "isNonExclusive": { "type": [ "null", "boolean" ] }, "isNonAdvisory": { "type": [ "null", "boolean" ] }, "privacyClass": { "type": "string" }, "processingBoundary": { "type": "string" }, "subprocessorDisclosure": { "type": "string" }, "subprocessorDisclosureVersion": { "type": "string" }, "managedAgentSessionCreated": { "type": "boolean" }, "managedAgentConsentRequired": { "type": "boolean" }, "eligibleForManagedAgentScan": { "type": "boolean" } } }, "FreeScanRequestDto": { "required": [ "email", "idea", "fingerprint" ], "type": "object", "properties": { "email": { "type": "string" }, "idea": { "type": "string" }, "fingerprint": { "type": [ "null", "string" ] }, "turnstileToken": { "type": [ "null", "string" ] }, "marketingConsent": { "type": "boolean", "default": false }, "managedAgentConsent": { "type": "boolean", "default": false }, "source": { "type": [ "null", "string" ] } } }, "FreeScanStatusLookupDto": { "required": [ "email", "lookupToken" ], "type": "object", "properties": { "email": { "type": "string" }, "lookupToken": { "type": "string" } } }, "FreeScanStatusLookupResultDto": { "required": [ "status", "message", "score", "verdictBand", "confidence", "summary", "findings", "risks", "nextSteps", "sources", "nextActionUrl" ], "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "score": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "verdictBand": { "type": [ "null", "string" ] }, "confidence": { "type": [ "null", "string" ] }, "summary": { "type": [ "null", "string" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/FreeAuditFindingDto" } }, "risks": { "type": "array", "items": { "type": "string" } }, "nextSteps": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/FreeAuditSourceDto" } }, "nextActionUrl": { "type": [ "null", "string" ] } } }, "OpportunityPurchaseDto": { "required": [ "immediateAccessConsent", "withdrawalLossAcknowledgment" ], "type": "object", "properties": { "immediateAccessConsent": { "type": "boolean" }, "withdrawalLossAcknowledgment": { "type": "boolean" } } }, "OpportunityTeaserDto": { "required": [ "id", "language", "audienceClass", "broadTrigger", "verificationSummary", "evidenceGrade", "sponsorDensityGrade", "sponsorProofSummary", "monetizationProofGrade", "riskGrade", "difficulty", "buyerFitProfile", "redactedIssueExamples" ], "type": "object", "properties": { "id": { "type": "string" }, "language": { "type": "string" }, "audienceClass": { "type": "string" }, "broadTrigger": { "type": "string" }, "verificationSummary": { "type": "string" }, "evidenceGrade": { "type": "string" }, "sponsorDensityGrade": { "type": "string" }, "sponsorProofSummary": { "type": "string" }, "monetizationProofGrade": { "type": "string" }, "riskGrade": { "type": "string" }, "difficulty": { "type": "string" }, "buyerFitProfile": { "type": "string" }, "redactedIssueExamples": { "type": "array", "items": { "type": "string" } } } }, "PaidProductRunCreatedDto": { "required": [ "runId", "status", "location", "idempotentReplay", "product" ], "type": "object", "properties": { "runId": { "type": "string" }, "status": { "type": "string" }, "location": { "type": "string" }, "idempotentReplay": { "type": "boolean" }, "product": { "type": "string" } } }, "PasswordResetCompletedDto": { "required": [ "status", "message" ], "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "PasswordResetCompleteDto": { "required": [ "token", "password", "confirmPassword" ], "type": "object", "properties": { "token": { "type": "string" }, "password": { "type": "string" }, "confirmPassword": { "type": "string" } } }, "PasswordResetLinkAcceptedDto": { "required": [ "status", "message", "expiresInMinutes", "developmentResetUrl" ], "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "expiresInMinutes": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "developmentResetUrl": { "type": [ "null", "string" ] } } }, "PasswordResetLinkRequestDto": { "required": [ "email" ], "type": "object", "properties": { "email": { "type": "string" } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "RunStatusDto": { "required": [ "runId", "status", "reason" ], "type": "object", "properties": { "runId": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": [ "null", "string" ] } } }, "SearchCreateDto": { "required": [ "operatorProfile", "expertise", "distributionChannels", "preferredMarkets", "languages", "budgetUsd", "hoursPerWeek", "goal", "constraints" ], "type": "object", "properties": { "operatorProfile": { "type": [ "null", "string" ] }, "expertise": { "type": [ "null", "array" ], "items": { "type": "string" } }, "distributionChannels": { "type": [ "null", "array" ], "items": { "type": "string" } }, "preferredMarkets": { "type": [ "null", "array" ], "items": { "type": "string" } }, "languages": { "type": [ "null", "array" ], "items": { "type": "string" } }, "budgetUsd": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "hoursPerWeek": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "goal": { "type": [ "null", "string" ] }, "constraints": { "type": [ "null", "array" ], "items": { "type": "string" } }, "candidateCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "consentToSeedCatalog": { "type": "boolean", "default": false }, "orderId": { "type": [ "null", "string" ], "format": "uuid" } } }, "SignInLinkAcceptedDto": { "required": [ "status", "message", "expiresInMinutes", "developmentSignInUrl" ], "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "expiresInMinutes": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "developmentSignInUrl": { "type": [ "null", "string" ] } } }, "SignInLinkRequestDto": { "required": [ "email" ], "type": "object", "properties": { "email": { "type": "string" }, "returnUrl": { "type": [ "null", "string" ] } } }, "SupportRequestAcceptedDto": { "required": [ "status", "message" ], "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "SupportRequestDto": { "required": [ "email", "topic", "message", "accountReference", "orderReference", "runReference" ], "type": "object", "properties": { "email": { "type": "string" }, "topic": { "type": "string" }, "message": { "type": "string" }, "accountReference": { "type": [ "null", "string" ] }, "orderReference": { "type": [ "null", "string" ] }, "runReference": { "type": [ "null", "string" ] } } }, "UsageBudgetBreachDto": { "required": [ "alertId", "runId", "userId", "occurredAt", "code", "severity", "budgetLimitUsd", "observedCostUsd", "message" ], "type": "object", "properties": { "alertId": { "type": "string" }, "runId": { "type": "string" }, "userId": { "type": [ "null", "string" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "code": { "type": "string" }, "severity": { "type": "string" }, "budgetLimitUsd": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "observedCostUsd": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "message": { "type": "string" } } }, "UsageConnectorCostDto": { "required": [ "connectorName", "unitCount", "costUsd" ], "type": "object", "properties": { "connectorName": { "type": "string" }, "unitCount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "costUsd": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" } } }, "UsageDashboardDto": { "required": [ "monthlyRunQuota", "runsUsed", "costThisMonth", "tokenTotals", "runs", "connectorCosts", "budgetBreaches" ], "type": "object", "properties": { "monthlyRunQuota": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "runsUsed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "costThisMonth": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "tokenTotals": { "$ref": "#/components/schemas/UsageTokenTotalsDto" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRunCostDto" } }, "connectorCosts": { "type": "array", "items": { "$ref": "#/components/schemas/UsageConnectorCostDto" } }, "budgetBreaches": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBudgetBreachDto" } } } }, "UsageRunCostDto": { "required": [ "runId", "userId", "lastUsageAt", "costUsd", "tokenTotals" ], "type": "object", "properties": { "runId": { "type": "string" }, "userId": { "type": [ "null", "string" ] }, "lastUsageAt": { "type": "string", "format": "date-time" }, "costUsd": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "tokenTotals": { "$ref": "#/components/schemas/UsageTokenTotalsDto" } } }, "UsageTokenTotalsDto": { "required": [ "llmInputTokens", "llmOutputTokens", "llmCacheCreationTokens", "llmCacheReadTokens", "webFetchTokens", "webSearchRequests", "erroredWebSearchRequests" ], "type": "object", "properties": { "llmInputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "llmOutputTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "llmCacheCreationTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "llmCacheReadTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "webFetchTokens": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "webSearchRequests": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "erroredWebSearchRequests": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" } } }, "WithdrawalCreateDto": { "required": [ "name", "electronicAddress", "contractIdentifier" ], "type": "object", "properties": { "name": { "type": "string" }, "electronicAddress": { "type": "string" }, "contractIdentifier": { "type": "string" } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "API keys are sent in the X-Api-Key header. Store only hashed keys server-side and rotate keys from the account administration surface.", "name": "X-Api-Key", "in": "header" } } }, "tags": [ { "name": "Free Scan", "description": "Public free-scan onboarding and confirmation endpoints." }, { "name": "Authentication", "description": "Passwordless account sign-in link requests." }, { "name": "Runs", "description": "Managed-agent run creation, status, and validated findings retrieval." }, { "name": "Reports", "description": "Rendered dossier and report output for completed runs." }, { "name": "Opportunities", "description": "Newsletter opportunity discovery and teaser data." }, { "name": "Commerce", "description": "Purchase workflows and Stripe-backed revenue operations." }, { "name": "Usage", "description": "Authenticated API usage, costs, limits, and budget telemetry." }, { "name": "Account", "description": "Account-level API metadata." }, { "name": "Developer", "description": "Machine-readable API contracts, schemas, SDK metadata, and onboarding links." }, { "name": "Withdrawals", "description": "Contributor payout request workflows." }, { "name": "Webhooks", "description": "Webhook endpoint management for platform events." }, { "name": "Health", "description": "Public liveness and version metadata." } ], "externalDocs": { "description": "Developer portal metadata", "url": "https://newsletteridea.com/v1/developer" } }