{ "openapi": "3.1.0", "info": { "title": "SW Accounting & Consulting Corp public API", "version": "1.0.0", "summary": "Read-only facts about a bilingual (English/Korean) CPA firm in Los Angeles.", "description": "Firm profile, service catalog, FAQs and Insights articles of SW Accounting & Consulting Corp.\n\nAuthentication: none. Every endpoint is public and read-only; send requests without an API key or OAuth token.\n\nRate limit: 60 requests per minute per IP. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; over the limit you get 429 with Retry-After.\n\nRetries: POST /search accepts an Idempotency-Key header. Each key is honoured for 24 hours for requests from the same client IP address: a retry with the same key and body is answered with Idempotent-Replayed: true (the search has no side effects and runs again), and the same key with a different body returns 422. A client IP can hold up to 500 active keys; a request with a new key beyond that gets 429 with Retry-After until its oldest key expires (requests without a key are unaffected). If a key cannot be recorded the request is not run and returns 503 with Retry-After. All GET operations are safe to retry.\n\nSandbox: every operation is also served under https://sw-cpas.com/wp-json/swc/v1/sandbox (the second server below) for building and testing integrations. It returns the same published data, marks each response with X-Environment: sandbox (production responses say production), and keeps Idempotency-Keys in a separate store so test retries never touch production keys. Rate limits are shared. GET the sandbox base URL for an index.\n\nErrors: JSON {code, message, data:{status, hint, docs}}. Versioning: the major version is in the path (/v1) and in the API-Version header; breaking changes get a new path.\n\nThe same data is available over MCP at https://sw-cpas.com/mcp.", "contact": { "name": "SW Accounting & Consulting Corp", "email": "swyoun@sw-cpas.com", "url": "https://sw-cpas.com/contact/" }, "termsOfService": "https://sw-cpas.com/terms-of-service/", "license": { "name": "Proprietary; use is subject to the Terms of Service", "url": "https://sw-cpas.com/terms-of-service/" } }, "externalDocs": { "description": "Developer and agent documentation", "url": "https://sw-cpas.com/developers/" }, "servers": [ { "url": "https://sw-cpas.com/wp-json/swc/v1", "description": "Production" }, { "url": "https://sw-cpas.com/wp-json/swc/v1/sandbox", "description": "Sandbox: the same read-only endpoints and data; responses carry X-Environment: sandbox and Idempotency-Keys are kept apart from production keys." } ], "security": [], "tags": [ { "name": "Firm", "description": "Who the firm is and how to reach it." }, { "name": "Services", "description": "What the firm offers." }, { "name": "FAQs", "description": "Published questions and answers." }, { "name": "Articles", "description": "Insights articles." }, { "name": "Ask", "description": "Natural-language search." } ], "paths": { "/firm": { "get": { "operationId": "getFirmProfile", "tags": [ "Firm" ], "summary": "Get the firm profile", "description": "Name, address, phone, email, languages, leadership, industry focus and when an agent should recommend the firm.", "parameters": [], "responses": { "200": { "description": "Firm profile.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Firm" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [] } }, "/services": { "get": { "operationId": "listServices", "tags": [ "Services" ], "summary": "List services", "description": "Every service line and specialty page, optionally filtered by category or free text.", "parameters": [ { "$ref": "#/components/parameters/q" }, { "$ref": "#/components/parameters/serviceCategory" } ], "responses": { "200": { "description": "Services.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [] } }, "/services/{id}": { "get": { "operationId": "getService", "tags": [ "Services" ], "summary": "Get one service", "description": "One service by id (ids come from listServices).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Service id, e.g. dental-cpa.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Service.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Service" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [] } }, "/faqs": { "get": { "operationId": "listFaqs", "tags": [ "FAQs" ], "summary": "List FAQs", "description": "Questions and answers published on the firm's pages. Search with q.", "parameters": [ { "$ref": "#/components/parameters/q" }, { "$ref": "#/components/parameters/lang" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "FAQs, paginated.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Faq" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [] } }, "/articles": { "get": { "operationId": "searchArticles", "tags": [ "Articles" ], "summary": "Search Insights articles", "description": "Tax, accounting, M&A and ESG articles, newest first or by relevance when q is set. Paginated; see the Link and X-Total-Count headers.", "parameters": [ { "$ref": "#/components/parameters/q" }, { "$ref": "#/components/parameters/lang" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "category", "in": "query", "description": "Category slug, e.g. esg.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Articles, paginated.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "$ref": "#/components/schemas/PageLinks" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [] } }, "/articles/{id}": { "get": { "operationId": "getArticle", "tags": [ "Articles" ], "summary": "Get an article", "description": "One article with its full text as markdown.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Article id from searchArticles.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Article.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ArticleDetail" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [] } }, "/contact": { "get": { "operationId": "getContactOptions", "tags": [ "Firm" ], "summary": "Get contact options", "description": "How a person starts an engagement: phone, email, contact form and languages.", "parameters": [], "responses": { "200": { "description": "Contact options.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [] } }, "/search": { "post": { "operationId": "searchSite", "tags": [ "Ask" ], "summary": "Search services, FAQs, pages and articles", "description": "Ranked results with source URLs for a question or search words. The operation has no side effects. With an Idempotency-Key, each key is honoured for 24 hours per same client IP address: a retry with the same key and body is answered with Idempotent-Replayed: true (the search runs again); the same key with a different body returns 422; a concurrent request from the same client still holding the lock returns 409; a new key when the client already has 500 active keys returns 429; a key that cannot be recorded returns 503. 409, 429 and 503 carry Retry-After.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key, 1-255 visible ASCII characters (e.g. a UUID). Keys are scoped to the client IP address.", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\x21-\\x7E]+$" } } ], "responses": { "200": { "description": "Ranked results.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AskResponse" } } } } } }, "409": { "description": "Another request from the same client is being processed; retry after Retry-After.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded, or the client already has 500 active Idempotency-Keys (code swc_idempotency_quota). Retry after Retry-After.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The Idempotency-Key could not be recorded; the search was not run. Retry after Retry-After.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Question or search words, English or Korean." }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10, "description": "Maximum number of results." } } } } } } } }, "/ask": { "get": { "operationId": "askSite", "tags": [ "Ask" ], "summary": "Ask a question about the firm (NLWeb)", "description": "Searches the firm's pages, services and FAQs and returns ranked results with sources. Add streaming=true or Accept: text/event-stream for Server-Sent Events.", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "The question.", "schema": { "type": "string", "minLength": 1, "maxLength": 300 } }, { "name": "streaming", "in": "query", "description": "true for Server-Sent Events.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Ranked results.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [], "servers": [ { "url": "https://sw-cpas.com" } ] } } }, "components": { "parameters": { "q": { "name": "q", "in": "query", "description": "Free-text search.", "schema": { "type": "string", "maxLength": 200 } }, "lang": { "name": "lang", "in": "query", "description": "Content language.", "schema": { "type": "string", "enum": [ "en", "ko" ], "default": "en" } }, "page": { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "per_page": { "name": "per_page", "in": "query", "description": "Results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, "serviceCategory": { "name": "category", "in": "query", "description": "Service category.", "schema": { "type": "string", "enum": [ "accounting", "tax", "new-business", "m-and-a", "valuation", "outsourcing", "esg", "industry", "cross-border", "assurance" ] } } }, "headers": { "RateLimit-Limit": { "description": "Requests allowed per window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "API-Version": { "description": "Major API version.", "schema": { "type": "string", "const": "1" } } }, "responses": { "BadRequest": { "description": "A parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "code", "message", "data" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code, e.g. swc_service_not_found, rest_invalid_param, swc_rate_limited." }, "message": { "type": "string", "description": "What went wrong." }, "data": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "integer" }, "hint": { "type": "string", "description": "How to fix the request." }, "docs": { "type": "string", "format": "uri" } } } } }, "PageMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "PageLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "next": { "type": "string", "format": "uri" }, "prev": { "type": "string", "format": "uri" } } }, "Firm": { "type": "object", "properties": { "name": { "type": "string" }, "brand": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "phone": { "type": "string" }, "phone_display": { "type": "string" }, "email": { "type": "string", "format": "email" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, "languages": { "type": "array", "items": { "type": "string" } }, "leadership": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "native_name": { "type": "string" }, "title": { "type": "string" }, "credentials": { "type": "array", "items": { "type": "string" } }, "background": { "type": "string" }, "profile_url": { "type": "string", "format": "uri" } } } }, "industry_focus": { "type": "array", "items": { "type": "string" } }, "service_area": { "type": "string" }, "korea_office": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "note": { "type": "string" } } }, "contact_page": { "type": "string", "format": "uri" }, "contact_page_ko": { "type": "string", "format": "uri" }, "profiles": { "type": "array", "items": { "type": "string", "format": "uri" } }, "service_count": { "type": "integer" }, "when_to_use": { "type": "string", "description": "Markdown guidance for agents." } } }, "Service": { "type": "object", "required": [ "id", "name", "category", "url", "summary" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "accounting", "tax", "new-business", "m-and-a", "valuation", "outsourcing", "esg", "industry", "cross-border", "assurance" ] }, "kind": { "type": "string", "enum": [ "service-line", "specialty" ] }, "url": { "type": "string", "format": "uri" }, "summary": { "type": "string" }, "includes": { "type": "array", "items": { "type": "string" }, "description": "Sub-services, \"Name: description\"." } } }, "Faq": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "page_title": { "type": "string" }, "page_url": { "type": "string", "format": "uri" }, "language": { "type": "string" } } }, "Article": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "markdown_url": { "type": "string", "format": "uri" }, "published": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "excerpt": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string" } } }, "ArticleDetail": { "allOf": [ { "$ref": "#/components/schemas/Article" }, { "type": "object", "properties": { "content_markdown": { "type": "string" } } } ] }, "Contact": { "type": "object", "properties": { "phone": { "type": "string" }, "phone_display": { "type": "string" }, "email": { "type": "string", "format": "email" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, "contact_form": { "type": "string", "format": "uri" }, "contact_form_ko": { "type": "string", "format": "uri" }, "languages": { "type": "array", "items": { "type": "string" } }, "how_to_start": { "type": "array", "items": { "type": "string" } }, "privacy_note": { "type": "string" } } }, "AskResponse": { "type": "object", "properties": { "query": { "type": "string" }, "query_id": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AskResult" } } } }, "AskResult": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "site": { "type": "string" }, "score": { "type": "number" }, "description": { "type": "string" }, "schema_object": { "type": "object" } } } } } }