> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rhetoric.law/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

The Rhetoric API allows you to interact with the platform programmatically. It
provides endpoints for managing the filing lifecycle. This reference describes
the protocol used to communicate with the API. It also provides detailed
information about each endpoint.

## Routing

The API is hosted at **[https://api.rhetoric.law](https://api.rhetoric.law)**. Endpoints are expressed as
RPC operations. That means all requests use the POST method, and the operation
name is passed in the path of the URL. For instance:

```shell theme={null}
curl -X POST https://api.rhetoric.law/create-filing-session
```

## Authentication

Authenticate requests using an API key provided as a bearer token. For example:

```shell theme={null}
--header "Authorization: Bearer $API_KEY"
```

You can create and manage API keys through the
[dashboard](https://dashboard.rhetoric.law/). API keys are like passwords. Keep
them secret, and do not commit them to source control.

## Requests

Provide request input as a JSON object in the body of the request, and set the
content type header to `application/json`.

```shell theme={null}
--header "Content-Type: application/json"
--data '{ "first_name": "Mustafa", "last_name": "Moiz" }'
```

## Responses

The shape of a response depends on the outcome of the request. A request can end
in a success, an application error, or a transport error. For more information
on errors, see [Errors](#errors).

### Success

A successful response returns a 200 HTTP status code and contains a JSON body
with `"result": "ok"` and the response data.

```json theme={null}
Status: 200 OK

{
  "result": "ok",
  "filing_id": "123",
  "filing_name": "Complaint"
}
```

### Application error

An application error returns a 200 HTTP status code and contains a JSON body
with a `"result": "err"` field and a machine-readable `"code"` that describes
the specific issue. It may also include additional fields related to the error.

```json theme={null}
Status: 200 OK

{
  "result": "err",
  "code": "file_too_large",
  "file_name": "complaint.pdf",
  "max_size": "35MB"
}
```

### Transport error

A transport error returns an appropriate HTTP status code. It may contain a JSON
body with additional detail.

```json theme={null}
Status: 401 Unauthorized

{ "message": "missing authentication token" }
```

## Errors

Rhetoric distinguishes between transport errors and application errors.

A **transport** error is one that arises as part of transmitting a request or a
response. Transport errors are raised when there is an issue with the
communication itself. For instance, you will encounter transport errors if you
use the incorrect request encoding, exceed the rate limit, or fail to provide an
API key in a request. Transport errors are surfaced using the appropriate HTTP
status code.

An **application** error is one that arises while processing a request.
Application errors occur when a request is received and understood but cannot be
fulfilled for some reason. Sometimes the issue is in the request, like when an
input parameter is too long. Other times the issue relates to a downstream
service, such as when a court imposes a blackout date on filing. Application
errors bear a 200 HTTP status code and are returned in the response body. The
body will include a `"code"` field with a machine readable error code for the
specific issue.

You can find the full list of transport errors below. All other errors will be
surfaced as application errors and are enumerated per operation.

| Code | Interpretation                                                                                    |
| ---- | ------------------------------------------------------------------------------------------------- |
| 200  | The request was processed. The `"result"` field distinguishes a success from an application error |
| 400  | Malformed request, such as invalid JSON or an incorrect request encoding                          |
| 401  | Missing or invalid API key                                                                        |
| 403  | The API key does not have permission for the requested operation                                  |
| 404  | The named operation does not exist                                                                |
| 429  | The rate limit for the API key has been exceeded                                                  |
| 500  | An unexpected error occurred on the server                                                        |