{"openapi":"3.1.0","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"Citia Engineering agent API","version":"1.0.0","summary":"Read the Citia product and service catalog and submit requests for quotation (RFQ).","description":"Public API for AI agents and procurement systems acting for Citia customers.\n\nCatalog reads work without a key at 20 requests/minute and 500/day per IP. Submitting and tracking RFQs needs an agent key: `Authorization: Bearer cak_...`.\nScopes: `catalog:read`, `rfq:write`, `rfq:read`. Each key has its own per-minute and per-day limits.\nKeys are issued by Citia on request (siTia on WhatsApp or the contact form: https://citia-engineering.com/en/contact).\n\nPrices are never published here. Every RFQ is reviewed by Citia engineers, who reply by email with a quotation.","contact":{"name":"Citia Engineering Indonesia","url":"https://citia-engineering.com/en/contact"},"termsOfService":"https://citia-engineering.com/en/terms"},"servers":[{"url":"https://revcm.citia-engineering.com/api/v1/agent","description":"Production"}],"externalDocs":{"description":"Overview for AI agents (llms.txt)","url":"https://citia-engineering.com/llms.txt"},"tags":[{"name":"Catalog","description":"Published products and services. No prices."},{"name":"RFQ","description":"Requests for quotation and their status."}],"paths":{"/catalog":{"get":{"operationId":"listCatalog","tags":["Catalog"],"summary":"List or search products and services","security":[{},{"agentKey":["catalog:read"]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"description":"Words to search for; every word must match."},{"name":"kind","in":"query","schema":{"type":"string","enum":["product","service"]}},{"name":"family","in":"query","schema":{"type":"string","maxLength":40},"description":"INTEGRA, CATALYST, ORSYNA or Engineering."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Matching items, best match first.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current 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"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogList"}}}},"400":{"description":"Invalid query parameter (`error`: `invalid_request`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked agent key (`error`: `unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this operation needs (`error`: `insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached (`error`: `rate_limited`). Wait `Retry-After` seconds.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current 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":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/catalog/{slug}":{"get":{"operationId":"getCatalogItem","tags":["Catalog"],"summary":"One product or service with features, specifications and FAQ","security":[{},{"agentKey":["catalog:read"]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"responses":{"200":{"description":"The item.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current 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"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogDetail"}}}},"401":{"description":"Missing, malformed, unknown or revoked agent key (`error`: `unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this operation needs (`error`: `insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No published item with this slug (`error`: `not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached (`error`: `rate_limited`). Wait `Retry-After` seconds.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current 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":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfq":{"post":{"operationId":"submitRfq","tags":["RFQ"],"summary":"Submit a request for quotation","description":"Creates an RFQ for the Citia team. Send an `Idempotency-Key` header to retry safely: the same key from the same agent key returns the first RFQ (200) instead of a new one.","security":[{"agentKey":["rfq:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":100,"pattern":"^[\\x21-\\x7e]+$"},"description":"Any unique string per RFQ, e.g. a UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqRequest"}}}},"responses":{"200":{"description":"Replay of an earlier request with the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqCreated"}}}},"201":{"description":"RFQ received.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current 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"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqCreated"}}}},"400":{"description":"Invalid body (`error`: `invalid_request`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked agent key (`error`: `unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this operation needs (`error`: `insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An item slug is not in the catalog (`error`: `unknown_item`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached (`error`: `rate_limited`). Wait `Retry-After` seconds.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current 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":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfq/{reference}":{"get":{"operationId":"getRfqStatus","tags":["RFQ"],"summary":"Status of an RFQ submitted with the same key","security":[{"agentKey":["rfq:read"]}],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","pattern":"^RFQ-\\d{2}-\\d{6,9}$"}}],"responses":{"200":{"description":"Current status.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current 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"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqStatus"}}}},"401":{"description":"Missing, malformed, unknown or revoked agent key (`error`: `unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this operation needs (`error`: `insufficient_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No RFQ with this reference for this key (`error`: `not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached (`error`: `rate_limited`). Wait `Retry-After` seconds.","headers":{"RateLimit-Limit":{"description":"Requests allowed in the current 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":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Catalog"],"summary":"This document","security":[{}],"responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{}}}}}}},"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","bearerFormat":"cak_ agent key","description":"Agent key issued by Citia. Scopes: catalog:read, rfq:write, rfq:read."}},"schemas":{"L10n":{"type":"object","description":"Text in English (always) and Indonesian (when written).","required":["en"],"properties":{"en":{"type":"string"},"id":{"type":"string"}},"additionalProperties":false},"CatalogItem":{"type":"object","required":["slug","kind","name","availability","url","pricing","updatedAt"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Use this in RFQ items[].slug."},"kind":{"type":"string","enum":["product","service"]},"family":{"type":["string","null"],"description":"Product family: INTEGRA, CATALYST, ORSYNA or Engineering."},"name":{"$ref":"#/components/schemas/L10n"},"summary":{"oneOf":[{"$ref":"#/components/schemas/L10n"},{"type":"null"}]},"model":{"type":["string","null"],"description":"Device model or part code, e.g. CT-BC."},"availability":{"type":"string","enum":["available","in_development"]},"integrations":{"type":"array","items":{"type":"string"}},"audience":{"type":"array","items":{"type":"string"}},"scope":{"type":"array","items":{"type":"string"}},"industries":{"type":"array","items":{"type":"string"}},"url":{"type":"object","required":["en","id"],"properties":{"en":{"type":"string","format":"uri"},"id":{"type":"string","format":"uri"}},"description":"Public product page in English and Indonesian."},"image":{"type":["string","null"],"format":"uri"},"master":{"oneOf":[{"type":"object","required":["code","category","tags"],"properties":{"code":{"type":"string"},"category":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}}}},{"type":"null"}],"description":"Citia product register code, category and tags, when the page follows a register entry."},"pricing":{"type":"object","required":["model","note"],"properties":{"model":{"type":"string","const":"quote_on_request"},"note":{"type":"string"}},"description":"No prices are published. Ask for a quotation with POST /rfq."},"updatedAt":{"type":"string","format":"date-time"}}},"CatalogDetail":{"allOf":[{"$ref":"#/components/schemas/CatalogItem"},{"type":"object","required":["features","specs","faq"],"properties":{"description":{"oneOf":[{"$ref":"#/components/schemas/L10n"},{"type":"null"}]},"features":{"type":"array","items":{"type":"object","required":["title"],"properties":{"title":{"$ref":"#/components/schemas/L10n"},"text":{"oneOf":[{"$ref":"#/components/schemas/L10n"},{"type":"null"}]}}}},"specs":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"$ref":"#/components/schemas/L10n"},"value":{"$ref":"#/components/schemas/L10n"}}}},"faq":{"type":"array","items":{"type":"object","required":["q","a"],"properties":{"q":{"$ref":"#/components/schemas/L10n"},"a":{"$ref":"#/components/schemas/L10n"}}}}}}]},"CatalogList":{"type":"object","required":["data","count","generatedAt"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"count":{"type":"integer"},"generatedAt":{"type":"string","format":"date-time"}}},"RfqRequest":{"type":"object","additionalProperties":false,"required":["requester","site","need"],"properties":{"requester":{"type":"object","additionalProperties":false,"required":["name","email"],"description":"The person Citia replies to.","properties":{"name":{"type":"string","maxLength":160},"email":{"type":"string","format":"email","maxLength":250},"organization":{"type":"string","maxLength":200},"phone":{"type":"string","maxLength":40,"pattern":"^[0-9 +()-]+$"}}},"site":{"type":"object","additionalProperties":false,"required":["city"],"description":"Where the work or delivery happens.","properties":{"name":{"type":"string","maxLength":200,"description":"Facility name, e.g. a terminal or plant."},"city":{"type":"string","maxLength":120},"province":{"type":"string","maxLength":120},"country":{"type":"string","pattern":"^[A-Z]{2}$","default":"ID","description":"ISO 3166-1 alpha-2."}}},"need":{"type":"string","minLength":10,"maxLength":5000,"description":"What is needed and why, in plain words: current equipment, problem, scope."},"items":{"type":"array","maxItems":30,"items":{"type":"object","additionalProperties":false,"required":["quantity","unit"],"description":"Give `slug` (from GET /catalog) or `description`, or both.","properties":{"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","maxLength":160},"description":{"type":"string","maxLength":300},"quantity":{"type":"number","exclusiveMinimum":0,"maximum":1000000,"multipleOf":0.001},"unit":{"type":"string","maxLength":20,"examples":["unit","lot","tank","site","m","month"]},"specs":{"type":"string","maxLength":1000,"description":"Technical details: models, interfaces, ranges."}}}},"timeline":{"type":"object","additionalProperties":false,"properties":{"neededBy":{"type":"string","format":"date","description":"Not in the past, at most 3 years ahead."},"notes":{"type":"string","maxLength":500}}},"attachments":{"type":"array","maxItems":10,"description":"Links to drawings or documents. Public https URLs only; files are not uploaded here.","items":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":500,"pattern":"^https://"},"name":{"type":"string","maxLength":160}}}},"language":{"type":"string","enum":["id","en"],"default":"en","description":"Language for Citia replies."}}},"RfqCreated":{"type":"object","required":["reference","status","receivedAt","statusUrl"],"properties":{"reference":{"type":"string","examples":["RFQ-26-000123"]},"status":{"type":"string","const":"received"},"receivedAt":{"type":"string","format":"date-time"},"statusUrl":{"type":"string","format":"uri","description":"GET this with the same key to follow the RFQ."},"duplicate":{"type":"boolean","description":"true when this answers a replayed Idempotency-Key."}}},"RfqStatus":{"type":"object","required":["reference","status","statusLabel","receivedAt","updatedAt","statusUrl"],"properties":{"reference":{"type":"string","pattern":"^RFQ-\\d{2}-\\d{6,9}$","examples":["RFQ-26-000123"]},"status":{"type":"string","enum":["received","reviewing","quoted","closed"],"description":"received: logged; reviewing: an engineer is working on it; quoted: a quotation was sent by email; closed: no further action."},"statusLabel":{"$ref":"#/components/schemas/L10n"},"publicNote":{"type":["string","null"],"description":"Message from the Citia team for the requester."},"receivedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"statusChangedAt":{"type":"string","format":"date-time"},"statusUrl":{"type":"string","format":"uri"},"itemCount":{"type":"integer"}}},"Error":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer"},"error":{"type":"string","enum":["invalid_request","unauthorized","insufficient_scope","not_found","unknown_item","rate_limited","unavailable"]},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}},"retryAfter":{"type":"integer"}}}}}}