{"openapi":"3.1.0","info":{"title":"withbrightcode Public API","version":"1.0.0","summary":"Public product APIs for Brightcode (withbrightcode.com)","description":"Brightcode public HTTP APIs for agents and integrations at withbrightcode.com. Brightcode public REST APIs are versioned under `/api/v1/`. Unversioned `/api/audit/*` and `/api/forms/*` paths are legacy aliases of v1 and may emit Deprecation/Sunset headers after 2026-12-31. Breaking changes ship only in a new major version (for example `/api/v2/`) with at least 90 days notice via Deprecation and Sunset response headers plus updates to `/openapi.json` and `/developers/withbrightcode`. Non-breaking additions (new optional fields, new endpoints) may land in v1 without a version bump. Payload CMS GraphQL at `/api/graphql` is **not** a public agent API — it requires admin authentication and is blocked from crawlers. Rate limits: successful audit starts are capped per IP per UTC day; report unlocks are capped per email per UTC day. Responses include RateLimit-* headers and Retry-After on HTTP 429. Probe GET `/api/v1/status` or GET `/openapi.json` without authentication to verify live RateLimit-* headers.","contact":{"name":"Brightcode","email":"hello@withbrightcode.com","url":"https://withbrightcode.com/developers/withbrightcode"},"license":{"name":"Proprietary","url":"https://withbrightcode.com/terms-conditions"}},"servers":[{"url":"https://withbrightcode.com/api/v1","description":"REST API v1 (current)"},{"url":"https://withbrightcode.com","description":"Site root (discovery + legacy aliases)"}],"tags":[{"name":"Audit","description":"Free website audit job lifecycle (rate-limited)"},{"name":"Forms","description":"Public lead / contact form submissions"},{"name":"Discovery","description":"Machine-readable indexes for agents"}],"paths":{"/status":{"get":{"operationId":"getApiV1Status","tags":["Discovery"],"summary":"API v1 status probe","description":"Unauthenticated health and versioning probe. Returns API-Version and RateLimit-* headers on every response.","servers":[{"url":"https://withbrightcode.com/api/v1"}],"responses":{"200":{"description":"API online","headers":{"API-Version":{"schema":{"type":"string","example":"1"},"description":"Current REST API major version"},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"apiVersion":{"type":"string"},"openapi":{"type":"string","format":"uri"},"developers":{"type":"string","format":"uri"},"deprecationPolicy":{"type":"string"}}}}}}}}},"/audit/run":{"post":{"operationId":"startWebsiteAuditV1","tags":["Audit"],"summary":"Start a free website audit (v1)","description":"Queues a PageSpeed + on-page audit for a public URL. Limit: 2 live starts per IP per UTC day. Returns RateLimit-* and API-Version headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditRunRequest"}}}},"responses":{"200":{"description":"Audit job created or cache hit","headers":{"API-Version":{"schema":{"type":"string","example":"1"},"description":"Current REST API major version"},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditRunResponse"}}}},"400":{"description":"Invalid URL or captcha","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"429":{"description":"Daily IP limit reached","headers":{"Retry-After":{"schema":{"type":"integer"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/audit/{id}/status":{"get":{"operationId":"getAuditStatusV1","tags":["Audit"],"summary":"Poll audit job status (v1)","description":"Returns progress for an audit job id from `/api/v1/audit/run`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":8},"description":"Audit job id"}],"responses":{"200":{"description":"Job status","headers":{"API-Version":{"schema":{"type":"string","example":"1"},"description":"Current REST API major version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditStatusResponse"}}}},"404":{"description":"Unknown job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/audit/{id}/unlock":{"post":{"operationId":"unlockAuditReportV1","tags":["Audit"],"summary":"Unlock full audit report by email (v1)","description":"Emails a magic link / unlocks the full report. Limit: 1 unlock(s) per email per UTC day.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Audit job id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditUnlockRequest"}}}},"responses":{"200":{"description":"Unlock accepted","headers":{"API-Version":{"schema":{"type":"string","example":"1"},"description":"Current REST API major version"},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Email daily unlock limit reached","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/forms/submit":{"post":{"operationId":"submitPublicFormV1","tags":["Forms"],"summary":"Submit a public lead form (v1)","description":"Accepts roadmap, contact, audit-request, or WhatsApp lead payloads. Persists locally and emails the Brightcode team when Brevo is configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmissionRequest"}}}},"responses":{"200":{"description":"Submission accepted","headers":{"API-Version":{"schema":{"type":"string","example":"1"},"description":"Current REST API major version"},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmissionResponse"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","tags":["Discovery"],"summary":"OpenAPI specification","description":"Returns this OpenAPI 3.1 document for function-calling and API discovery.","servers":[{"url":"https://withbrightcode.com"}],"responses":{"200":{"description":"OpenAPI document","headers":{"API-Version":{"schema":{"type":"string","example":"1"},"description":"Current REST API major version"},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","tags":["Discovery"],"summary":"llms.txt agent index","description":"Markdown index of Brightcode pages and when-to-use guidance for agents.","servers":[{"url":"https://withbrightcode.com"}],"responses":{"200":{"description":"llms.txt markdown","content":{"text/plain":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}}}}}},"/developers/withbrightcode":{"get":{"operationId":"getWithbrightcodeDeveloperResources","tags":["Discovery"],"summary":"withbrightcode developer resources","description":"Official withbrightcode.com developer hub: OpenAPI, REST v1, auth notes, and rate limits. Supports Accept: text/markdown.","servers":[{"url":"https://withbrightcode.com"}],"responses":{"200":{"description":"HTML or Markdown documentation page","content":{"text/html":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}}}}}},"/developers":{"get":{"operationId":"getDevelopersPage","tags":["Discovery"],"summary":"Brightcode developers & agents hub","description":"Human and agent documentation hub. Supports Accept: text/markdown content negotiation.","servers":[{"url":"https://withbrightcode.com"}],"responses":{"200":{"description":"HTML or Markdown documentation page","content":{"text/html":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}}}}}},"/api/audit/run":{"post":{"operationId":"startWebsiteAuditLegacy","tags":["Audit"],"summary":"Start a free website audit (legacy alias)","description":"Queues a PageSpeed + on-page audit for a public URL. Limit: 2 live starts per IP per UTC day. Returns RateLimit-* and API-Version headers. **Deprecated:** prefer `/api/v1/audit/run`. May emit Deprecation and Sunset headers after 2026-12-31.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditRunRequest"}}}},"responses":{"200":{"description":"Audit job created or cache hit","headers":{"API-Version":{"schema":{"type":"string","example":"1"},"description":"Current REST API major version"},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditRunResponse"}}}},"400":{"description":"Invalid URL or captcha","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"429":{"description":"Daily IP limit reached","headers":{"Retry-After":{"schema":{"type":"integer"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"deprecated":true}},"/api/forms/submit":{"post":{"operationId":"submitPublicFormLegacy","tags":["Forms"],"summary":"Submit a public lead form (legacy alias)","description":"Accepts roadmap, contact, audit-request, or WhatsApp lead payloads. Persists locally and emails the Brightcode team when Brevo is configured. **Deprecated:** prefer `/api/v1/forms/submit`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmissionRequest"}}}},"responses":{"200":{"description":"Submission accepted","headers":{"API-Version":{"schema":{"type":"string","example":"1"},"description":"Current REST API major version"},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmissionResponse"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"deprecated":true}}},"components":{"schemas":{"ErrorMessage":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"ok":{"type":"boolean"}},"additionalProperties":true},"FormSubmissionRequest":{"type":"object","required":["kind","data"],"properties":{"kind":{"type":"string","enum":["roadmap","contact","audit","whatsapp"],"description":"Form kind"},"data":{"type":"object","additionalProperties":true,"description":"Kind-specific fields (name, email, phone, goalType, …)"},"meta":{"type":"object","properties":{"source":{"type":"string"},"pagePath":{"type":"string"}},"additionalProperties":true}}},"FormSubmissionResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"message":{"type":"string"},"emailed":{"type":"boolean"}}},"AuditRunRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public website URL to audit"},"turnstileToken":{"type":"string","description":"Cloudflare Turnstile token when captcha is enabled"}}},"AuditRunResponse":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Audit job id"},"cached":{"type":"boolean"},"dailyLimitReached":{"type":"boolean"}}},"AuditStatusResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","complete","failed"]},"stage":{"type":"string"},"progress":{"type":"number"},"url":{"type":"string"}},"additionalProperties":true},"AuditUnlockRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}}}}},"x-brightcode-api-versioning":{"currentVersion":"1","versionHeader":"API-Version","deprecationHeader":"Deprecation","sunsetHeader":"Sunset","policy":"Brightcode public REST APIs are versioned under `/api/v1/`. Unversioned `/api/audit/*` and `/api/forms/*` paths are legacy aliases of v1 and may emit Deprecation/Sunset headers after 2026-12-31. Breaking changes ship only in a new major version (for example `/api/v2/`) with at least 90 days notice via Deprecation and Sunset response headers plus updates to `/openapi.json` and `/developers/withbrightcode`. Non-breaking additions (new optional fields, new endpoints) may land in v1 without a version bump.","canonicalPrefix":"/api/v1","legacyAliasesUntil":"2026-12-31"},"x-brightcode-agent":{"brand":"Brightcode","legalName":"Brightcode Technologies","domain":"withbrightcode.com","developerResources":"https://withbrightcode.com/developers/withbrightcode","whenToUse":["Need a Delhi NCR / remote web agency for websites, ecommerce, apps, SEO, ads, or hosting care","Want machine-readable Brightcode service discovery via llms.txt and OpenAPI","Running a free website audit against a public URL"],"notFor":["Payload CMS GraphQL introspection as a public schema","Authenticated admin operations"]}}