{"openapi":"3.1.0","info":{"title":"ArmsLength AI OECD Guidelines API","version":"1.0.0","summary":"Paragraph-level retrieval for the OECD Transfer Pricing Guidelines 2022.","description":"A read-only retrieval API for searching and fetching OECD Transfer Pricing Guidelines paragraphs and preparing bounded context packs. API output supports research and citation workflows; users remain responsible for checking the official OECD publication and applicable law.","contact":{"name":"ArmsLength AI Support","url":"https://armslength.ai/contact","email":"support@armslength.ai"},"license":{"name":"Proprietary — public API access subject to ArmsLength AI terms","identifier":"LicenseRef-ArmsLength-AI-API"}},"servers":[{"url":"https://armslength.ai","description":"Production"}],"externalDocs":{"description":"ArmsLength AI developer resources","url":"https://armslength.ai/developers"},"tags":[{"name":"OECD retrieval","description":"Authenticated retrieval operations over the OECD Transfer Pricing Guidelines 2022."},{"name":"Access","description":"API-key registration."}],"paths":{"/api/oecd/v1/search":{"get":{"operationId":"searchOecdGuidelines","summary":"Search OECD Guidelines paragraphs","description":"Searches indexed OECD Transfer Pricing Guidelines 2022 paragraphs. Returns bounded results with paragraph references, context and relevance scores.","tags":["OECD retrieval"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"Natural-language query between 2 and 500 characters.","schema":{"type":"string","minLength":2,"maxLength":500}},{"name":"top_k","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"chapters","in":"query","description":"Optional comma-separated Roman-numeral chapter filters, for example I,II,VI.","schema":{"type":"string","examples":["I,VI"]}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"500":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"503":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}},"/api/oecd/v1/paragraphs":{"get":{"operationId":"getOecdParagraphs","summary":"Retrieve OECD paragraphs by reference","description":"Returns up to 20 exact paragraph references together with chapter, section, heading path and neighboring references.","tags":["OECD retrieval"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"refs","in":"query","required":true,"description":"Comma-separated OECD paragraph references, for example 1.6,2.14,6.32.","schema":{"type":"string","minLength":1,"examples":["1.6,2.14,6.32"]}}],"responses":{"200":{"description":"Paragraphs keyed by requested reference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParagraphsResponse"}}}},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"500":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"503":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}},"/api/oecd/v1/context-pack":{"get":{"operationId":"createOecdContextPack","summary":"Create an OECD context pack","description":"Retrieves a bounded set of relevant paragraphs and a citation string for grounding an LLM or research workflow.","tags":["OECD retrieval"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"topic","in":"query","required":true,"description":"Topic or question between 2 and 500 characters.","schema":{"type":"string","minLength":2,"maxLength":500}},{"name":"max_paragraphs","in":"query","description":"Maximum number of paragraphs in the pack.","schema":{"type":"integer","minimum":1,"maximum":30,"default":15}},{"name":"chapters","in":"query","description":"Optional comma-separated chapter filters.","schema":{"type":"string","examples":["I,VI"]}},{"name":"format","in":"query","description":"Adds a formatted Markdown context field when set to markdown.","schema":{"type":"string","enum":["json","markdown"],"default":"json"}}],"responses":{"200":{"description":"Context pack","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextPackResponse"}}}},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"500":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"503":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}},"/api/oecd/v1/register":{"post":{"operationId":"requestOecdApiKey","summary":"Request an OECD API key","description":"Requests delivery of a free API key by email. The response is deliberately identical for new and previously registered addresses.","tags":["Access"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationRequest"}}}},"responses":{"200":{"description":"Registration request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationResponse"}}}},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"413":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"500":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"503":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Free API key requested through https://armslength.ai/resources/oecd-api."}},"schemas":{"ApiProblem":{"type":"object","additionalProperties":false,"required":["type","title","status","code","message","error","resolution","docs"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"code":{"type":"string","pattern":"^[A-Z0-9_]+$"},"message":{"type":"string"},"error":{"type":"string","description":"Compatibility alias for message."},"resolution":{"type":"string"},"docs":{"type":"string","format":"uri"}}},"Paragraph":{"type":"object","required":["paragraph_ref","chapter","text"],"properties":{"paragraph_ref":{"type":"string","examples":["1.6"]},"chapter":{"type":"string"},"section":{"type":["string","null"]},"heading_path":{"type":"array","items":{"type":"string"}},"text":{"type":"string"},"neighbors":{"type":"object","properties":{"prev":{"type":["string","null"]},"next":{"type":["string","null"]}}}}},"SearchResult":{"allOf":[{"$ref":"#/components/schemas/Paragraph"},{"type":"object","required":["snippet","scores"],"properties":{"snippet":{"type":"string"},"scores":{"type":"object","required":["semantic","lexical","combined"],"properties":{"semantic":{"type":"number"},"lexical":{"type":"number"},"combined":{"type":"number"}}}}}]},"SearchResponse":{"type":"object","required":["query","results","total","mode"],"properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"total":{"type":"integer","minimum":0},"mode":{"type":"string","enum":["hybrid","lexical_fallback"]},"suggestions":{"type":"array","items":{"type":"string"}}}},"ParagraphsResponse":{"type":"object","required":["paragraphs","not_found"],"properties":{"paragraphs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Paragraph"}},"not_found":{"type":"array","items":{"type":"string"}}}},"ContextPackResponse":{"type":"object","required":["pack_id","topic","paragraphs","total","citation"],"properties":{"pack_id":{"type":"string"},"topic":{"type":"string"},"paragraphs":{"type":"array","items":{"$ref":"#/components/schemas/Paragraph"}},"total":{"type":"integer","minimum":0},"formatted_context":{"type":"string"},"citation":{"type":"object","required":["format","paragraph_refs","citation_string"],"properties":{"format":{"type":"string","const":"OECD TPG (2022)"},"paragraph_refs":{"type":"array","items":{"type":"string"}},"citation_string":{"type":"string"}}}}},"RegistrationRequest":{"type":"object","additionalProperties":false,"required":["name","email"],"properties":{"name":{"type":"string","minLength":2,"maxLength":120},"email":{"type":"string","format":"email","maxLength":320},"company":{"type":"string","maxLength":200}}},"RegistrationResponse":{"type":"object","additionalProperties":false,"required":["success","message"],"properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"}}}}}}