{"openapi":"3.1.0","info":{"title":"GST Cranes — Companies API","version":"0.1.0","description":"Read-only public API for GST Cranes company and fleet-record discovery. Clients may send GST-API-Version: 2026-07-06 to pin integration expectations. Deprecation policy: breaking changes are announced in developer docs and, where applicable, with Deprecation and Sunset response headers before removal.","x-developerResources":{"canonical":"https://gstcranes.com/developer-resources","apiDocumentation":"https://gstcranes.com/developers","markdown":"https://gstcranes.com/developer-resources.md","apiDocumentationMarkdown":"https://gstcranes.com/developers.md"}},"externalDocs":{"description":"GST Cranes API deprecation and versioning policy","url":"https://gstcranes.com/docs/api/deprecation-policy"},"servers":[{"url":"https://gstcranes.com","description":"Production"}],"paths":{"/api/companies":{"get":{"operationId":"listCompanies","summary":"List companies","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"country","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"service_type","in":"query","schema":{"type":"string","enum":["mobile_crane","crawler_crane","aerial_platform","heavy_haulage"]}},{"name":"capacity_min_t","in":"query","schema":{"type":"number"}},{"name":"bbox","in":"query","schema":{"type":"string","description":"minLon,minLat,maxLon,maxLat"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"List of public companies","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyList"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/companies/{slug}":{"get":{"operationId":"getCompanyBySlug","summary":"Get a company by slug","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Company detail","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCompany"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/companies/batch":{"post":{"operationId":"batchGetCompaniesBySlug","summary":"Batch get companies by slug","description":"Read-only batch lookup for public company records. Accepts up to 50 slugs and returns active public companies in request order.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCompanyRequest"}}}},"responses":{"200":{"description":"Batch public company lookup result","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCompanyResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/sandbox/first-call":{"get":{"operationId":"getSandboxFirstCall","summary":"Run the zero-auth sandbox first API call","description":"Read-only sandbox environment for agents to make a first API call without an API key, account session, credit spend, or data mutation.","parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Sandbox first-call response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxFirstCall"},"examples":{"readOnlyFirstCall":{"summary":"Read-only sandbox first API call","value":{"ok":true,"mode":"sandbox","auth":"none","side_effects":false,"read_only":true,"mutates":[],"writes":false,"message":"GST Cranes read-only sandbox first API call. No API key is required and no account data is accessed.","sample_curl":"curl https://gstcranes.com/api/sandbox/first-call","next":{"developer_resources":"https://gstcranes.com/developer-resources","developers":"https://gstcranes.com/developers","developer_resources_markdown":"https://gstcranes.com/developer-resources.md","auth":"https://gstcranes.com/auth.md","openapi":"https://gstcranes.com/.well-known/openapi.json","companies":"https://gstcranes.com/api/companies?country=DE&limit=10"}}}}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/ask":{"post":{"operationId":"askPublicResourceRouter","summary":"Ask the public GST Cranes resource router","description":"Read-only natural-language resource routing for public marketplace, wanted-ad, Crane Wiki, and developer resources. This endpoint has no side effects; clients may still send Idempotency-Key for replay-safe agent integrations.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}}},"responses":{"200":{"description":"Public resource-routing answer","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskResponse"}},"text/event-stream":{"schema":{"type":"string"},"examples":{"message":{"value":"event: message\\ndata: {\"answer\":{\"text\":\"GST Cranes can help...\"}}\\n\\nevent: done\\ndata: {\"ok\":true}\\n\\n"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/.well-known/api-catalog":{"get":{"operationId":"getApiCatalog","summary":"Get the GST Cranes API catalog","description":"Public read-only discovery resource for agents and crawlers. This endpoint has no side effects and requires no API key.","parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Get the GST Cranes API catalog","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/.well-known/ai-catalog.json":{"get":{"operationId":"getAiCatalog","summary":"Get the GST Cranes AI catalog","description":"Public read-only discovery resource for agents and crawlers. This endpoint has no side effects and requires no API key.","parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Get the GST Cranes AI catalog","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/.well-known/mcp/server-card.json":{"get":{"operationId":"getMcpServerCard","summary":"Get the GST Cranes MCP server card","description":"Public read-only discovery resource for agents and crawlers. This endpoint has no side effects and requires no API key.","parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Get the GST Cranes MCP server card","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/docs/mcp/server-card.json":{"get":{"operationId":"getMcpDocsCanonicalServerCard","summary":"Get the GST Cranes public docs MCP canonical server card","description":"Public read-only discovery resource for agents and crawlers. This endpoint has no side effects and requires no API key.","parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Get the GST Cranes public docs MCP canonical server card","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/.well-known/mcp/docs/server-card.json":{"get":{"operationId":"getMcpDocsServerCard","summary":"Get the GST Cranes public docs MCP server card","description":"Public read-only discovery resource for agents and crawlers. This endpoint has no side effects and requires no API key.","parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Get the GST Cranes public docs MCP server card","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"parameters":{"ApiVersion":{"name":"GST-API-Version","in":"header","required":false,"schema":{"type":"string","example":"2026-07-06"},"description":"Optional version pin. Omit for the current public API contract, or send 2026-07-06 for explicit agent integrations."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Optional replay-safety key for agent clients. Public read endpoints have no side effects; write endpoints that spend credits or publish content remain browser-session workflows."}},"headers":{"RateLimitLimit":{"description":"Maximum request count in the current rate-limit window.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Remaining request count in the current rate-limit window.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Unix timestamp when the current rate-limit window resets.","schema":{"type":"integer"}},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"Deprecation":{"description":"RFC 9745 Deprecation signal. Present only when an API version or behavior is being deprecated.","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594 Sunset signal. Present only when a deprecated API version has a planned removal date.","schema":{"type":"string","format":"date-time"}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"TooManyRequests":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error":{"description":"Machine-readable API error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_request"},"message":{"type":"string","example":"The request could not be processed."},"resolution":{"type":"string","example":"Check the request parameters and retry with a valid payload."}}}}},"CompanyList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicCompany"}},"next_cursor":{"type":["string","null"]}}},"BatchCompanyRequest":{"type":"object","required":["slugs"],"properties":{"slugs":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":120}}},"additionalProperties":false},"BatchCompanyResponse":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicCompany"}}}},"SandboxFirstCall":{"type":"object","required":["ok","mode","auth","side_effects","read_only","mutates","writes","message","sample_curl","next"],"properties":{"ok":{"type":"boolean","const":true},"mode":{"type":"string","const":"sandbox"},"auth":{"type":"string","const":"none"},"side_effects":{"type":"boolean","const":false},"read_only":{"type":"boolean","const":true},"mutates":{"type":"array","items":{"type":"string"},"maxItems":0},"writes":{"type":"boolean","const":false},"message":{"type":"string"},"sample_curl":{"type":"string"},"next":{"type":"object","required":["developer_resources","developers","developer_resources_markdown","auth","openapi","companies"],"properties":{"developer_resources":{"type":"string","format":"uri"},"developers":{"type":"string","format":"uri"},"developer_resources_markdown":{"type":"string","format":"uri"},"auth":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"companies":{"type":"string","format":"uri"}}}}},"PublicCompany":{"type":"object","required":["id","slug","name","country","lat","lon","services","fleet_highlights"],"properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"logo_url":{"type":["string","null"]},"cover_image_url":{"type":["string","null"]},"website":{"type":["string","null"]},"phone":{"type":["string","null"]},"whatsapp":{"type":["string","null"]},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state_region":{"type":["string","null"]},"country":{"type":"string"},"postal_code":{"type":["string","null"]},"lat":{"type":"number"},"lon":{"type":"number"},"tier":{"type":"string","enum":["free","featured"]},"services":{"type":"array","items":{"type":"string"}},"fleet_highlights":{"type":"array","items":{"$ref":"#/components/schemas/FleetHighlight"}}}},"FleetHighlight":{"type":"object","properties":{"brand":{"type":["string","null"]},"model":{"type":["string","null"]},"capacity_t":{"type":["number","null"]},"boom_type":{"type":["string","null"]},"max_height_m":{"type":["number","null"]}}},"AskRequest":{"type":"object","properties":{"query":{"type":"string","description":"Natural-language question about public GST Cranes resources."},"q":{"type":"string","description":"Short alias for query."}},"additionalProperties":false},"AskResponse":{"type":"object","required":["_meta","answer","results"],"properties":{"_meta":{"type":"object","properties":{"response_type":{"type":"string","example":"answer"},"response_format":{"type":"string","example":"conversational_search"},"version":{"type":"string","example":"0.1"}}},"answer":{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}},"results":{"type":"array","items":{"type":"object","properties":{"@type":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"}}}}}}}}}