Skip to main content
This guide sets up an integration where an AI agent, rather than a human in a browser, drives the filing through a filing session. It follows the same shape as the quickstart: create a filer, create a session, then hand the session off, but the handoff is to an agent instead of to a frontend component. In broad strokes, this is the process:
  • Create an API key
  • Install the API client on your backend
  • Create a filer and a filing session
  • Hand the agent the session token, the skill file, and a document
  • Listen for filing events

​
Create an API key

You use API keys to authenticate requests to the Rhetoric API. Create one from the dashboard. Each key is scoped to an environment: live or test. Filings submitted using a test key do not get sent to a real court. Use a test key while you build out your integration. Treat API keys like passwords. Keep them on your backend, and do not commit them to source control or expose them to the browser or an agent.

​
Install the API client on your backend

The Rhetoric API client is a TypeScript package that exposes all of the operations provided by our API. It is meant to be used on your backend. You can install it using the following command:
Once the package is installed, create a client like so:

​
Create a filer

A filer represents an entity that files documents through Rhetoric, such as an individual or an organization. A filer typically corresponds one to one with a user of your platform. Call create filer on the backend the first time a user of your platform needs to file something, and associate the returned filer ID with your user. On subsequent filings for the same user, reuse that ID rather than creating a new filer.

​
Create a filing session

A filing session holds the state of an in-progress filing. An agent can read and advance that session through the API. Call create filing session with the ID of the filer conducting the filing.
This operation returns a sessionToken. It authenticates the two operations an agent uses to drive the session, is scoped to this session only, and is only returned once at creation time. It cannot be recovered later, so capture it before handing it off.

​
Hand the session to an agent

Unlike your API key, which should stay on your backend, a session token is scoped to a single filing session and is safe to hand to whatever drives that session: in this case, an agent. Give the agent three things:
  1. The sessionToken from the previous step.
  2. A pointer to the skill file at docs.rhetoric.law/.well-known/skills/filing-session/skill.md, which tells it how to call resume-filing-session and apply-filing-session-event to read and advance the form.
  3. Whatever documents the filing requires, so it can attach them when it reaches the appropriate step, and so that it can extract the relevant information.
How you hand these pieces of information off depends on your agent framework; it might be done as a tool call, as part of its initial prompt, or however else it consumes instructions and files. Where a human filer would read the rendered Element and respond to it, the agent instead resumes the session, reads the returned form, and applies events to fill fields, upload documents, and trigger actions, repeating until the form is driven to submission. You can try this out yourself before wiring up a real agent. Point an agent at a test session and walk it through a test filing using a demo account:
1

Select a court system

Choose California.
2

Select court

Choose Santa Cruz - Civil.
3

Log in

Log in using our test account. The username is mustafa+prose-demo@rhetoric.law and the password is Hellorhetoric1.
4

Choose a filing type

Choose New case.
5

Select case category

Choose Civil - Unlimited.
6

Select case type

Choose Breach of Contract/Warranty.
7

Add parties

This filing requires two parties. Add Mustafa Moiz as a plaintiff, and add Hamza Surti as a defendant. For each party, set the party kind to Individual. Mustafa Moiz should be designated as the filer.
8

Add a filing entry

Add a filing entry with the filing code Complaint. Add a document to the entry with the document type Public. Have the agent attach this sample complaint as a placeholder. It has one page.
9

Select a payment account

Use our test payment method, listed as Credit card.
10

Review fees

The fee review step shows the total cost of filing as well as the line items that contribute to that cost.
11

Disclaimers

Check the box to agree to the eService Agreement.
12

Review and submit

The final review step shows a summary of the filing, including the routing info, parties, documents, and payment account. Confirm that the selections match the guidance above, then trigger the submit action to submit the filing.

​
Listen for the submission webhook

When the agent completes the session, Rhetoric sends a filing submitted event to any webhook you have registered. Register a webhook endpoint from the dashboard to be notified, rather than polling the API for status changes. See the webhooks guide for details on registering endpoints, retries, and idempotency, and the webhooks reference for the events Rhetoric can send.

​
Next steps

If you want a deeper understanding of the domain, our filing primer provides a high level overview of the efiling system and the core concepts involved. For detailed information about the endpoints Rhetoric offers and the patterns we follow, see the API reference. For the contract an agent uses to drive a session, see the Filing session skill file.