{"openapi":"3.1.0","info":{"title":"ListShack Agent API","version":"2.0.0","description":"The REST API behind the ListShack MCP server. Most agents should connect to the MCP server at `https://listshack.com/api/mcp` instead; every MCP tool maps to one operation below.\n\n## Authentication\n\nOAuth 2.1 Authorization Code with PKCE. The person connecting the agent signs in to ListShack, chooses an account and approves ListShack capabilities; send the access token as `Authorization: Bearer <access_token>`. There are no static API keys.\n\n## Typical flow\n\n1. `GET /api/v1/access-status` — plan, capabilities and remaining free calls.\n2. `GET /api/v1/databases` and `/api/v1/databases/{databaseId}` — what can be searched.\n3. `POST /api/v1/search-field-values` and `/api/v1/count-records` — explore values and counts.\n4. `POST /api/v1/searches`, then quote and purchase — the person who connected the agent confirms every purchase.\n\nRetry a failed metered or purchase request with its original `X-ListShack-Request-Id`; identical retries are never charged twice.","contact":{"name":"ListShack","url":"https://listshack.com"}},"servers":[{"url":"https://listshack.com"}],"security":[{"ListShackOAuth":[]}],"tags":[{"name":"Databases","description":"Databases an agent may search and their searchable fields. Catalog reads are free."},{"name":"Access","description":"Plan, capabilities, free allowance and credits for the account the agent was connected to."}],"paths":{"/api/v1/databases":{"get":{"tags":["Databases"],"summary":"List Databases","description":"**List searchable ListShack databases.**\n\nReturns stable database IDs and descriptive metadata. It does not expose physical search index names or record data. Catalog reads are free and do not consume the monthly allowance.\n\n**Required ListShack capabilities:** `catalog.read`","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["databases"],"properties":{"databases":{"type":"array","items":{"type":"object","required":["id","searchable","datasetVersion","type","title","description","releasedDate","geographyFields","filterCategories","searchableFields","outputFields","useCases","creditMultiplier","appliedPolicySummaries"],"properties":{"id":{"type":"string","description":"Stable ListShack dictionary identifier; physical search index names are not exposed."},"searchable":{"type":"boolean","description":"Whether this dataset is enabled for versioned search requests."},"datasetVersion":{"type":["string","null"],"description":"Dataset release or validated mapping-contract version."},"type":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"releasedDate":{"type":["string","null"],"format":"date"},"geographyFields":{"type":"array","items":{"type":"string"}},"filterCategories":{"type":"array","items":{"type":"string"}},"searchableFields":{"type":"array","items":{"type":"object","required":["name","type","operators"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","date"]},"operators":{"type":"array","items":{"type":"string","enum":["eq","neq","gt","gte","lt","lte","in","like","exists","missing"]}}}}},"outputFields":{"type":"array","items":{"type":"string"}},"useCases":{"type":"array","items":{"type":"object","required":["id","description"],"properties":{"id":{"type":"string"},"description":{"type":"string"}}}},"creditMultiplier":{"type":["number","null"],"minimum":0},"appliedPolicySummaries":{"type":"array","items":{"type":"object","required":["id","mandatory","description"],"properties":{"id":{"type":"string"},"mandatory":{"type":"boolean"},"description":{"type":"string"}}}}}}}}}}}},"401":{"description":"Missing token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The OAuth grant does not include catalog.read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Delegated agent traffic limit reached. Traffic admission uses RATE_LIMITED, independently of successful-call quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the relevant quota or traffic window resets.","schema":{"type":"integer","minimum":1}}}},"503":{"description":"Agent traffic admission is temporarily unavailable. REQUEST_TIMEOUT ends the response after 20 seconds. RESPONSE_TOO_LARGE rejects a response exceeding 1048576 payload bytes before headers start; an oversized partial stream is closed. Retry a mutating or metered request using its original request ID; a durable transaction may already have been accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-listshack-capabilities":["catalog.read"]}},"/api/v1/databases/{databaseId}":{"get":{"tags":["Databases"],"summary":"Describe Database","description":"**Describe a searchable ListShack database.**\n\nReturns stable database metadata and the geographic/filter categories available for that dataset. Catalog reads are free and do not consume the monthly allowance.\n\n**Required ListShack capabilities:** `catalog.read`","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["id","searchable","datasetVersion","type","title","description","releasedDate","geographyFields","filterCategories","searchableFields","outputFields","useCases","creditMultiplier","appliedPolicySummaries"],"properties":{"id":{"type":"string","description":"Stable ListShack dictionary identifier; physical search index names are not exposed."},"searchable":{"type":"boolean","description":"Whether this dataset is enabled for versioned search requests."},"datasetVersion":{"type":["string","null"],"description":"Dataset release or validated mapping-contract version."},"type":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"releasedDate":{"type":["string","null"],"format":"date"},"geographyFields":{"type":"array","items":{"type":"string"}},"filterCategories":{"type":"array","items":{"type":"string"}},"searchableFields":{"type":"array","items":{"type":"object","required":["name","type","operators"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","date"]},"operators":{"type":"array","items":{"type":"string","enum":["eq","neq","gt","gte","lt","lte","in","like","exists","missing"]}}}}},"outputFields":{"type":"array","items":{"type":"string"}},"useCases":{"type":"array","items":{"type":"object","required":["id","description"],"properties":{"id":{"type":"string"},"description":{"type":"string"}}}},"creditMultiplier":{"type":["number","null"],"minimum":0},"appliedPolicySummaries":{"type":"array","items":{"type":"object","required":["id","mandatory","description"],"properties":{"id":{"type":"string"},"mandatory":{"type":"boolean"},"description":{"type":"string"}}}}}}}}},"401":{"description":"Missing token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The OAuth grant does not include catalog.read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Delegated agent traffic limit reached. Traffic admission uses RATE_LIMITED, independently of successful-call quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds until the relevant quota or traffic window resets.","schema":{"type":"integer","minimum":1}}}},"503":{"description":"Agent traffic admission is temporarily unavailable. REQUEST_TIMEOUT ends the response after 20 seconds. RESPONSE_TOO_LARGE rejects a response exceeding 1048576 payload bytes before headers start; an oversized partial stream is closed. Retry a mutating or metered request using its original request ID; a durable transaction may already have been accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-listshack-capabilities":["catalog.read"],"parameters":[{"name":"databaseId","in":"path","required":true,"schema":{"type":"string"},"description":"Stable ListShack dictionary identifier."}]}},"/api/v1/access-status":{"get":{"tags":["Access"],"summary":"Get Access Status","description":"**Get the current delegated API access and usage status.**\n\nReturns current server-verified OAuth identity scopes, ListShack grant capabilities, account tier, free usage and eligible paid credit availability. First-party browser sessions do not receive the promotional agent allowance.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["tier","accountRole","selectedAccount","oauthIdentityScopes","capabilities","planRestrictions","freeUsage","creditAvailability","upgradeUrl"],"properties":{"tier":{"type":"string"},"accountRole":{"type":"string"},"selectedAccount":{"type":"object","required":["accountUid","role"],"properties":{"accountUid":{"type":"string"},"role":{"type":"string"}}},"oauthIdentityScopes":{"type":"array","items":{"type":"string"}},"capabilities":{"type":"array","items":{"type":"string"}},"planRestrictions":{"type":"object","required":["perDownloadLimit","searchSuppressions","verifiedMembership"],"properties":{"perDownloadLimit":{"type":"integer","minimum":0},"searchSuppressions":{"type":"boolean"},"verifiedMembership":{"type":"boolean"}}},"freeUsage":{"type":"object","required":["policyVersion","period","limit","used","remaining","resetsAt"],"additionalProperties":false,"properties":{"policyVersion":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._-]+$"},"period":{"type":"string","enum":["calendar_month_utc"]},"unlimited":{"type":"boolean"},"limit":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991},"used":{"type":"integer","minimum":0,"maximum":9007199254740991},"remaining":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991},"resetsAt":{"type":"string","maxLength":32,"format":"date-time","pattern":"^\\d{4}-\\d{2}-01T00:00:00(?:\\.000)?Z$"}}},"creditAvailability":{"anyOf":[{"type":"null"},{"type":"object","required":["monthly","addOn","perDownloadLimit"],"properties":{"monthly":{"type":"integer","minimum":0},"addOn":{"type":"integer","minimum":0},"perDownloadLimit":{"type":"integer","minimum":0}}}]},"upgradeUrl":{"anyOf":[{"type":"null"},{"type":"string","format":"uri"}]}}}}}},"401":{"description":"Missing token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A current delegated OAuth grant and selected account are required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Free usage allowance is exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The request exceeded its response deadline. REQUEST_TIMEOUT ends the response after 20 seconds. RESPONSE_TOO_LARGE rejects a response exceeding 1048576 payload bytes before headers start; an oversized partial stream is closed. Retry a mutating or metered request using its original request ID; a durable transaction may already have been accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ListShackOAuth":{"type":"oauth2","description":"Supabase Auth Authorization Code with PKCE. OAuth scopes identify the user; ListShack capabilities are granted and enforced separately.","flows":{"authorizationCode":{"authorizationUrl":"https://listshack.com/supabase/auth/v1/oauth/authorize","tokenUrl":"https://listshack.com/supabase/auth/v1/oauth/token","scopes":{"openid":"Authenticate the user","profile":"Read basic profile claims","email":"Read email claim","phone":"Read phone claims","offline_access":"Request refresh-token access"}}},"x-pkce":true}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"retryAfterSeconds":{"type":"integer","minimum":1},"resetsAt":{"type":"string","format":"date-time"},"dimension":{"type":"string","enum":["account","client","credential","operation"]},"required_capability":{"type":"string"},"required_capabilities":{"type":"array","items":{"type":"string"}}}},"TypedFilterNode":{"oneOf":[{"type":"object","required":["and"],"additionalProperties":false,"properties":{"and":{"type":"array","minItems":1,"maxItems":8,"items":{"$ref":"#/components/schemas/TypedFilterNode"}}}},{"type":"object","required":["or"],"additionalProperties":false,"properties":{"or":{"type":"array","minItems":1,"maxItems":8,"items":{"$ref":"#/components/schemas/TypedFilterNode"}}}},{"type":"object","required":["not"],"additionalProperties":false,"properties":{"not":{"$ref":"#/components/schemas/TypedFilterNode"}}},{"type":"object","required":["field","operator"],"additionalProperties":false,"properties":{"field":{"type":"string","enum":["state","city","county","age","gender","homeowner","make","modelYear"]},"operator":{"type":"string","enum":["exists","missing"]}}},{"type":"object","required":["field","operator","value"],"additionalProperties":false,"properties":{"field":{"type":"string","enum":["state","city","county","age","gender","homeowner","make","modelYear"]},"operator":{"type":"string","enum":["eq","neq","gt","gte","lt","lte","in","like"]},"value":{"oneOf":[{"type":"string","maxLength":128},{"type":"number"},{"type":"boolean"},{"type":"array","minItems":1,"maxItems":20,"items":{"oneOf":[{"type":"string","maxLength":128},{"type":"number"},{"type":"boolean"}]}}]}}}]}}}}