Introduction - Rhetoric

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. 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:

curl -X POST https://api.rhetoric.law/create-filing-session

Authentication

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

--header "Authorization: Bearer $API_KEY"

You can create and manage API keys through the dashboard. 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.

--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.

Success

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

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.

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.

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

​Routing

​Authentication

​Requests

​Responses

​Success

​Application error

​Transport error

​Errors