{
  "openapi": "3.1.0",
  "info": {
    "title": "Arakan Lexara — UAE Regulatory Library API",
    "version": "1.0.0",
    "description": "Lexara is a free, machine-readable library of UAE laws, regulations, rulebooks and circulars. Use this API to search regulations by keyword, browse laws by authority or jurisdiction, read individual articles and obligations, and retrieve amendment history. No authentication is required. All data relates to the United Arab Emirates regulatory environment. Authorities include VARA (Virtual Assets), DFSA (DIFC Financial Services), ADGM (Abu Dhabi), CBUAE (Central Bank), FTA (Federal Tax), and more.",
    "contact": {
      "name": "Arakan",
      "url": "https://www.arakan.ae",
      "email": "api@arakan.ae"
    },
    "license": {
      "name": "Free for AI and developer use",
      "url": "https://www.arakan.ae/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.arakan.ae/api/lexara",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Search",
      "description": "Full-text search across all UAE regulations and obligations in the library."
    },
    {
      "name": "Laws",
      "description": "Browse and retrieve specific laws, rulebooks, and regulations by jurisdiction or authority."
    },
    {
      "name": "Articles",
      "description": "Read individual articles, clauses, and obligations from a specific law, including compliance guidance and evidence requirements."
    },
    {
      "name": "Amendments",
      "description": "Retrieve the history of regulatory changes and amendments, optionally filtered by authority."
    },
    {
      "name": "Authorities",
      "description": "List all UAE regulatory authorities available in the library with their law counts."
    }
  ],
  "paths": {
    "/explorer": {
      "post": {
        "operationId": "searchRegulations",
        "summary": "Search UAE regulations by keyword or question",
        "description": "Full-text semantic search across all articles, obligations and regulatory clauses in the Lexara library. Accepts natural language queries (e.g. 'VARA marketing rules for crypto', 'DFSA client money requirements', 'VAT registration threshold'). Returns matching articles ranked by relevance, each with the source law, clause reference, plain-English summary, and compliance guidance. Use this as the primary entry point when a user asks a regulatory question about the UAE.",
        "tags": ["Search"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Natural language search query. Can be a keyword, phrase, or question about UAE regulations. Examples: 'VARA client agreement requirements', 'AML screening obligations', 'trade licence renewal', 'ADGM data protection'.",
                    "example": "VARA requirements for marketing virtual assets"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List of matching regulatory articles ranked by relevance.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/SearchResult" }
                }
              }
            }
          },
          "400": {
            "description": "Query parameter missing or empty.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/laws": {
      "get": {
        "operationId": "listLaws",
        "summary": "List UAE laws and rulebooks in the library",
        "description": "Returns all in-force laws, rulebooks, and regulations available in Lexara. Can be filtered by jurisdiction (e.g. 'vara', 'dfsa', 'adgm', 'federal') or authority slug (e.g. 'vara', 'dfsa', 'fta', 'cbuae'). Use this to discover what is available before fetching articles, or to list all regulations from a specific regulator. Each law includes topic tags, version, effective date, and a link to the official source.",
        "tags": ["Laws"],
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "query",
            "required": false,
            "description": "Filter by jurisdiction. Use 'vara' for Virtual Assets Regulatory Authority laws, 'dfsa' for DIFC Financial Services Authority, 'adgm' for Abu Dhabi Global Market, 'federal' for UAE federal laws.",
            "schema": {
              "type": "string",
              "enum": ["vara", "dfsa", "adgm", "federal", "cbuae", "sca", "difc"]
            }
          },
          {
            "name": "authority",
            "in": "query",
            "required": false,
            "description": "Filter by regulatory authority slug. Examples: 'vara', 'dfsa', 'fta', 'cbuae', 'mohre'.",
            "schema": { "type": "string" },
            "example": "vara"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Keyword search on law name or topic tags.",
            "schema": { "type": "string" },
            "example": "market conduct"
          }
        ],
        "responses": {
          "200": {
            "description": "List of laws matching the filters.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Law" }
                }
              }
            }
          }
        }
      }
    },
    "/laws/{lawId}/articles": {
      "get": {
        "operationId": "getLawArticles",
        "summary": "Get all articles and obligations from a specific law",
        "description": "Returns every article, clause, and obligation within a specific law or rulebook, in order. Each article includes: the clause reference (e.g. 'II.A.1'), the obligation in plain English, step-by-step compliance guidance, the evidence required to demonstrate compliance, frequency (ONE_OFF / ONGOING / QUARTERLY / ANNUAL / EVENT_TRIGGERED), risk level, and the primary responsible function. Use the law's 'id' field from the /laws endpoint as the lawId path parameter.",
        "tags": ["Articles"],
        "parameters": [
          {
            "name": "lawId",
            "in": "path",
            "required": true,
            "description": "The UUID of the law from the /laws endpoint. Example: the id field returned in a Law object.",
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Ordered list of articles/obligations in the law.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Article" }
                }
              }
            }
          },
          "404": {
            "description": "Law not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/amendments": {
      "get": {
        "operationId": "listAmendments",
        "summary": "List recent regulatory amendments and changes",
        "description": "Returns the most recent amendments to UAE laws and regulations in reverse chronological order. Each amendment includes what changed, the previous text, the new text, the amendment date, and the source URL. Use this to answer questions like 'what has changed in VARA regulations recently?' or 'when was the DFSA GEN module last updated?'. Filter by authority slug to narrow to a specific regulator.",
        "tags": ["Amendments"],
        "parameters": [
          {
            "name": "authority",
            "in": "query",
            "required": false,
            "description": "Filter amendments to a specific regulatory authority by slug. Examples: 'vara', 'dfsa', 'fta'.",
            "schema": { "type": "string" },
            "example": "vara"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of amendments to return. Default 50, maximum 200.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of amendments ordered newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Amendment" }
                }
              }
            }
          }
        }
      }
    },
    "/authorities": {
      "get": {
        "operationId": "listAuthorities",
        "summary": "List all UAE regulatory authorities in the library",
        "description": "Returns all regulatory authorities whose laws are indexed in Lexara, along with the number of in-force laws available for each. Use this to discover which regulators are covered and their slug identifiers (used as filter values in the /laws and /amendments endpoints). Federal authorities appear first.",
        "tags": ["Authorities"],
        "responses": {
          "200": {
            "description": "List of regulatory authorities with law counts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Authority" }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResult": {
        "type": "object",
        "description": "A single matching article or regulatory clause returned by the search endpoint.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for this article."
          },
          "article_number": {
            "type": "string",
            "description": "The clause or article reference as it appears in the official law. Examples: 'II.A.1', 'I.B.3', 'Article 4(2)'."
          },
          "title": {
            "type": "string",
            "description": "The section heading this article falls under."
          },
          "body_text": {
            "type": "string",
            "description": "The full text of the regulatory obligation or provision, as stated in the law."
          },
          "ai_summary": {
            "type": "string",
            "description": "A concise plain-English summary of what this article requires, written for practical compliance use."
          },
          "law_id": {
            "type": "string",
            "format": "uuid",
            "description": "The UUID of the parent law. Use this with /laws/{lawId}/articles to fetch all articles from the same law."
          },
          "law_short_name": {
            "type": "string",
            "description": "Short display name of the parent law. Example: 'VARA Market Conduct', 'DFSA GEN'."
          },
          "law_slug": {
            "type": "string",
            "description": "URL-safe slug of the parent law. Example: 'vara-market-conduct'."
          },
          "jurisdiction": {
            "type": "string",
            "description": "The regulatory jurisdiction this law belongs to. Examples: 'vara', 'dfsa', 'federal'."
          },
          "authority_slug": {
            "type": "string",
            "description": "The slug of the issuing regulatory authority. Examples: 'vara', 'dfsa', 'fta', 'cbuae'."
          },
          "rank": {
            "type": "number",
            "description": "Relevance score from the full-text search engine. Higher = more relevant."
          }
        }
      },
      "Law": {
        "type": "object",
        "description": "A law, rulebook, regulation or circular in the Lexara library.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier. Pass to /laws/{lawId}/articles to fetch all articles."
          },
          "slug": {
            "type": "string",
            "description": "URL-safe identifier for this law. Example: 'vara-market-conduct', 'dfsa-gen'."
          },
          "short_name": {
            "type": "string",
            "description": "Short display name. Example: 'VARA Market Conduct', 'DFSA GEN'."
          },
          "full_name": {
            "type": "string",
            "description": "Full official name of the law or rulebook."
          },
          "jurisdiction": {
            "type": "string",
            "description": "Jurisdiction slug. Examples: 'vara', 'dfsa', 'adgm', 'federal'."
          },
          "topic_tags": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Subject matter tags for this law. Examples: ['vasp', 'market-conduct', 'client-agreements', 'complaints']."
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to the official published version of this law."
          },
          "current_version": {
            "type": "string",
            "description": "Version identifier as published by the authority."
          },
          "effective_date": {
            "type": "string",
            "format": "date",
            "description": "Date this law came into force."
          },
          "last_amended": {
            "type": "string",
            "format": "date",
            "description": "Date of the most recent amendment."
          },
          "status": {
            "type": "string",
            "enum": ["in_force", "superseded", "draft"],
            "description": "Current status of this law. Only 'in_force' laws are returned by default."
          },
          "authority_slug": {
            "type": "string",
            "description": "Slug of the issuing authority."
          },
          "authority_name": {
            "type": "string",
            "description": "Full name of the issuing authority. Example: 'Virtual Assets Regulatory Authority'."
          }
        }
      },
      "Article": {
        "type": "object",
        "description": "A single article, clause, or obligation from a law. Includes full compliance guidance.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "article_number": {
            "type": "string",
            "description": "Clause reference as it appears in the law. Example: 'II.A.1', 'I.B.3(a)'."
          },
          "title": {
            "type": "string",
            "description": "Section heading."
          },
          "body_text": {
            "type": "string",
            "description": "Full regulatory text of the obligation."
          },
          "ai_summary": {
            "type": "string",
            "description": "Plain-English action summary of what the obligation requires."
          },
          "guidance_text": {
            "type": "string",
            "description": "Step-by-step compliance guidance including what is required, how to comply, what evidence to retain, and who is responsible. Formatted in Markdown."
          },
          "evidence_text": {
            "type": "string",
            "description": "The specific documentation or records that must be maintained to demonstrate compliance with this obligation."
          },
          "frequency": {
            "type": "string",
            "enum": ["ONE_OFF", "ONGOING", "ANNUAL", "QUARTERLY", "EVENT_TRIGGERED", "PERIODIC_UNSPECIFIED"],
            "description": "How often this obligation must be performed or reviewed."
          },
          "risk_level": {
            "type": "string",
            "enum": ["LOW", "MEDIUM", "HIGH"],
            "description": "Risk level associated with non-compliance."
          },
          "primary_function": {
            "type": "string",
            "description": "The business function primarily responsible for this obligation. Example: 'Compliance', 'Legal', 'IT / Information Security'."
          },
          "sub_register": {
            "type": "string",
            "description": "Classification of this article within the law. Examples: 'Foundation', 'Ongoing', 'Event-Triggered', 'Periodic'."
          },
          "licence_scope": {
            "type": "string",
            "description": "The licence type or entity type this obligation applies to. Example: 'VASP', 'CUSTODY_CSD'."
          },
          "position": {
            "type": "integer",
            "description": "Ordering position of this article within the law."
          }
        }
      },
      "Amendment": {
        "type": "object",
        "description": "A recorded change or amendment to a UAE law or regulation.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "law_id": {
            "type": "string",
            "format": "uuid",
            "description": "The law that was amended."
          },
          "law_short_name": {
            "type": "string",
            "description": "Short name of the amended law."
          },
          "authority_slug": {
            "type": "string",
            "description": "Slug of the authority that issued the amendment."
          },
          "amendment_date": {
            "type": "string",
            "format": "date",
            "description": "Date the amendment took effect."
          },
          "description": {
            "type": "string",
            "description": "Plain-English description of what changed."
          },
          "previous_text": {
            "type": "string",
            "description": "The text before the amendment."
          },
          "new_text": {
            "type": "string",
            "description": "The text after the amendment."
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Link to the official amendment notice."
          }
        }
      },
      "Authority": {
        "type": "object",
        "description": "A UAE regulatory authority whose laws are indexed in Lexara.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string",
            "description": "Short identifier used as a filter value in other endpoints. Examples: 'vara', 'dfsa', 'fta', 'cbuae', 'mohre'."
          },
          "full_name_en": {
            "type": "string",
            "description": "Full English name of the authority. Example: 'Virtual Assets Regulatory Authority'."
          },
          "is_federal": {
            "type": "boolean",
            "description": "True if this is a UAE federal authority (e.g. FTA, MOHRE). False for emirate-level or free zone authorities."
          },
          "law_count": {
            "type": "integer",
            "description": "Number of in-force laws from this authority currently indexed in Lexara."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message."
          }
        }
      }
    }
  }
}