@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Open Policy Agent (OPA) REST API
@version 0.28.0
@endpoints 16
@toc policies(4), data(6), root(1), query(2), compile(1), health(1), config(1)

@group policies
@endpoint GET /v1/policies
@desc List policies
@optional {pretty: bool # If true, response will be in a human-readable format.}
@returns(200) {result: [any]} # Success
@errors {500: Server error}

@endpoint GET /v1/policies/{id}
@desc Get a policy module
@optional {pretty: bool # If true, response will be in a human-readable format.}
@returns(200) {result: [any]} # Success
@errors {404: Not found (for example, a requested policy module or document does not exist), 500: Server error}

@endpoint PUT /v1/policies/{id}
@desc Create or update a policy module
@optional {pretty: bool # If true, response will be in a human-readable format., metrics: bool # If true, compiler performance metrics will be returned in the response.}
@returns(200) {result: [any]} # Success
@errors {400: Bad request, 500: Server error}

@endpoint DELETE /v1/policies/{id}
@desc Delete a policy module
@optional {pretty: bool # If true, response will be in a human-readable format.}
@returns(200) Success
@errors {400: Bad request, 404: Not found (for example, a requested policy module or document does not exist), 500: Server error}

@endgroup

@group data
@endpoint GET /v1/data/{path}
@desc Get a document
@optional {input: map # Provide the text for an [input document](https://www.openpolicyagent.org/docs/latest/kubernetes-primer/#input-document) in JSON format, pretty: bool # If true, response will be in a human-readable format., provenance: bool # If true, response will include build and version information in addition to the result., explain: str # If set to *full*, response will include query explanations in addition to the result., metrics: bool # If true, compiler performance metrics will be returned in the response., instrument: bool # If true, response will return additional performance metrics in addition to the result and the standard metrics.  **Caution:** This can add significant overhead to query evaluation. The recommendation is to only use this parameter if you are debugging a performance problem.}
@returns(200) Success
@errors {400: Bad request, 500: Server error}

@endpoint PUT /v1/data/{path}
@desc Create or overwrite a document
@optional {If-None-Match: str # The server will respect the If-None-Match header if it is set to * (in other words, it will not overwrite an existing document located at the specified `path`).}
@returns(204) Success
@errors {304: Document was not modified, 400: Bad request, 404: Not found (for example, a requested policy module or document does not exist), 500: Server error}

@endpoint PATCH /v1/data/{path}
@desc Update a document
@returns(204) Success
@errors {400: Bad request, 404: Not found (for example, a requested policy module or document does not exist), 500: Server error}

@endpoint DELETE /v1/data/{path}
@desc Delete a document
@returns(204) Success
@errors {404: Not found (for example, a requested policy module or document does not exist), 500: Server error}

@endpoint POST /v1/data/{path}
@desc Get a document (with input)
@optional {pretty: bool # If true, response will be in a human-readable format., provenance: bool # If true, response will include build and version information in addition to the result., explain: str # If set to *full*, response will include query explanations in addition to the result., metrics: bool # If true, compiler performance metrics will be returned in the response., instrument: bool # If true, response will return additional performance metrics in addition to the result and the standard metrics.  **Caution:** This can add significant overhead to query evaluation. The recommendation is to only use this parameter if you are debugging a performance problem.}
@returns(200) Success
@errors {400: Bad request, 500: Server error}

@endpoint POST /v0/data/{path}
@desc Get a document (with webhook)
@optional {pretty: bool # If true, response will be in a human-readable format.}
@returns(200) Success
@errors {400: Bad request, 404: Not found (for example, a requested policy module or document does not exist), 500: Server error}

@endgroup

@group root
@endpoint POST /
@desc Execute a simple query
@optional {pretty: bool # If true, response will be in a human-readable format.}
@returns(200) Success
@errors {400: Bad request, 404: Not found (for example, a requested policy module or document does not exist), 500: Server error}

@endgroup

@group query
@endpoint GET /v1/query
@desc Execute an ad-hoc query (simple)
@required {q: str # The [URL-encoded](https://www.w3schools.com/tags/ref_urlencode.ASP) ad-hoc query to execute.}
@optional {pretty: bool # If true, response will be in a human-readable format., explain: str # If set to *full*, response will include query explanations in addition to the result., metrics: bool # If true, compiler performance metrics will be returned in the response.}
@returns(200) Success
@errors {400: Bad request, 500: Server error}

@endpoint POST /v1/query
@desc Execute an ad-hoc query (complex)
@optional {pretty: bool # If true, response will be in a human-readable format., explain: str # If set to *full*, response will include query explanations in addition to the result., metrics: bool # If true, compiler performance metrics will be returned in the response.}
@returns(200) Success
@errors {400: Bad request, 500: Server error, 501: Streaming not implemented}

@endgroup

@group compile
@endpoint POST /v1/compile
@desc Compile
@optional {pretty: bool # If true, response will be in a human-readable format., explain: str # If set to *full*, response will include query explanations in addition to the result., metrics: bool # If true, compiler performance metrics will be returned in the response., instrument: bool # If true, response will return additional performance metrics in addition to the result and the standard metrics.  **Caution:** This can add significant overhead to query evaluation. The recommendation is to only use this parameter if you are debugging a performance problem.}
@returns(200) Success
@errors {400: Bad request, 500: Server error}

@endgroup

@group health
@endpoint GET /health
@desc Health
@optional {bundles: bool # Reports on bundle activation status (useful for 'ready' checks at startup).  This includes any discovery bundles or bundles defined in the loaded discovery configuration., plugins: bool # Reports on plugin status, exclude-plugin: [str]= # String parameter to exclude a plugin from status checks. Can be added multiple times. Does nothing if plugins is not true. This parameter is useful for special use cases where a plugin depends on the server being fully initialized before it can fully initialize itself.}
@returns(200) OPA service is healthy
@errors {500: OPA service is not healthy}

@endgroup

@group config
@endpoint GET /v1/config
@desc Get configurations
@optional {pretty: bool # If true, response will be in a human-readable format.}
@returns(200) {result: map{services: map{acmecorp: map{url: str}}, labels: map{id: str, version: str}, keys: map{global-key: map{scope: str}}, decision_logs: map{service: str}, status: map{service: str}, bundles: map{authz: map{service: str}}, default_authorization_decision: str, default_decision: str}} # Success
@errors {500: Server error}

@endgroup

@end