# Download DOCX
Source: https://docs.abigail.app/api-reference/downloads/docx

api-reference/downloads/openapi.json get /v1/openclaw/download/{job_id}

Download a completed Response to Office Action document in DOCX format.

## Authentication

This endpoint uses **signed URL tokens** instead of API keys. The token is included
in the `download_url` from the Poll Draft Status endpoint response.

No `X-API-Key` header is needed -- the token IS the authentication.

## Token expiration

Download tokens expire after **1 hour**. If the token has expired, re-poll the
draft status endpoint to get a fresh URL:

```bash theme={null}
# Get fresh download URL
curl -H "X-API-Key: abi_sk_..." \
  https://api.abigail.app/v1/openclaw/draft-roa/status/roa_abc123

# Use the new download_url from the response
curl -o response.docx \
  "https://api.abigail.app/v1/openclaw/download/roa_abc123?token=eyJhbGci..."
```


# Get Deadlines
Source: https://docs.abigail.app/api-reference/free/deadlines

api-reference/free/openapi.json get /v1/openclaw/deadlines/{application_number}

<Note>
  This endpoint is free and requires no authentication.
</Note>

Returns response deadlines and critical deadlines for a patent application.
Use this to check if a response is due before running a paid analysis.


# Lookup Application
Source: https://docs.abigail.app/api-reference/free/lookup

api-reference/free/openapi.json get /v1/openclaw/lookup/{application_number}

<Note>
  This endpoint is free and requires no authentication.
</Note>

Application numbers are normalized automatically -- slashes, commas, and spaces are removed.
All of these formats work:

* `17200011`
* `17/200,011`
* `17 200 011`


# Openclaw Analyze
Source: https://docs.abigail.app/api-reference/openclaw/openclaw-analyze

https://api.abigail.app/v1/openclaw/openapi.json post /v1/openclaw/analyze
Run office action analysis. Requires API key.



# Openclaw Deadlines
Source: https://docs.abigail.app/api-reference/openclaw/openclaw-deadlines

https://api.abigail.app/v1/openclaw/openapi.json get /v1/openclaw/deadlines/{application_number}
Get deadlines for a patent application. Free, no auth required.



# Openclaw Download
Source: https://docs.abigail.app/api-reference/openclaw/openclaw-download

https://api.abigail.app/v1/openclaw/openapi.json get /v1/openclaw/download/{job_id}
Download a completed ROA DOCX. Authenticated via signed URL token.

The token is generated when the ROA draft job completes and included
in the job status response. No X-API-Key needed -- the token IS the auth.



# Openclaw Draft Roa
Source: https://docs.abigail.app/api-reference/openclaw/openclaw-draft-roa

https://api.abigail.app/v1/openclaw/openapi.json post /v1/openclaw/draft-roa
Submit async ROA drafting job. Returns job_id for polling. Requires API key.



# Openclaw Draft Roa Status
Source: https://docs.abigail.app/api-reference/openclaw/openclaw-draft-roa-status

https://api.abigail.app/v1/openclaw/openapi.json get /v1/openclaw/draft-roa/status/{job_id}
Poll ROA drafting job status. Requires API key.



# Openclaw Examiner
Source: https://docs.abigail.app/api-reference/openclaw/openclaw-examiner

https://api.abigail.app/v1/openclaw/openapi.json get /v1/openclaw/examiner/{examiner_name}
Get examiner intelligence profile. Requires API key.

Examiner name format: 'LASTNAME, FIRSTNAME M' (URL-encoded).
Example: /v1/openclaw/examiner/SMITH%2C%20JOHN%20A



# Openclaw Lookup
Source: https://docs.abigail.app/api-reference/openclaw/openclaw-lookup

https://api.abigail.app/v1/openclaw/openapi.json get /v1/openclaw/lookup/{application_number}
Look up a patent application by number. Free, no auth required.



# Analyze Office Action
Source: https://docs.abigail.app/api-reference/paid/analyze

api-reference/paid/openapi.json post /v1/openclaw/analyze

This is the core endpoint. Submit the full text of a USPTO office action and receive
a structured analysis with claim-by-claim breakdown, rejection bases, prior art mapping,
and strategic recommendations.

Every response includes [Glass Box](/concepts/glass-box) transparency metadata.

## Typical workflow

1. Call `/lookup/{app_number}` to get the examiner name
2. Call `/analyze` with the office action text
3. Use the returned `analysis_id` to call `/draft-roa`

## Office action types

| Code   | Meaning                       |
| ------ | ----------------------------- |
| `CTNF` | Non-final rejection (default) |
| `CTFR` | Final rejection               |
| `CTED` | Restriction requirement       |
| `CTRS` | Requirement for information   |

## Examiner intelligence

When `include_examiner_intel` is `true` (default), the analysis includes examiner
behavior patterns that inform the strategy recommendations. Set to `false` to skip
this step and reduce processing time.


# Draft Response Document
Source: https://docs.abigail.app/api-reference/paid/draft-roa

api-reference/paid/openapi.json post /v1/openclaw/draft-roa

Submits an asynchronous job to generate a Response to Office Action (ROA) document
in DOCX format. The job runs in the background via Celery workers.

## Async workflow

1. **Submit** this endpoint -- returns a `job_id` immediately
2. **Poll** `/draft-roa/status/{job_id}` until `status` is `complete`
3. **Download** the DOCX via the signed URL in the status response

## Strategy selections

Override the AI-recommended strategy for specific claims:

```json theme={null}
{
  "strategy_selections": {
    "claim_1": "amend_narrow",
    "claim_2": "argue_distinction",
    "claim_5": "cancel"
  }
}
```

| Strategy                   | Meaning                                                 |
| -------------------------- | ------------------------------------------------------- |
| `amend_narrow`             | Narrow the claim with additional limitations            |
| `argue_distinction`        | Argue that the claim is already distinct from prior art |
| `cancel`                   | Cancel the claim                                        |
| `argue_unexpected_results` | Argue unexpected results (for 103 rejections)           |

If `strategy_selections` is empty or omitted, the AI recommendations from the
analysis are used.


# Examiner Intelligence
Source: https://docs.abigail.app/api-reference/paid/examiner

api-reference/paid/openapi.json get /v1/openclaw/examiner/{examiner_name}

Get an intelligence profile for a USPTO patent examiner, including historical
allowance rates, rejection patterns, and interview success rates.

## Name format

Examiner names must be in `LASTNAME, FIRSTNAME M` format and URL-encoded:

```
/v1/openclaw/examiner/SMITH%2C%20JOHN%20A
```

<Tip>
  Use the `/lookup` endpoint first to get the exact examiner name from a
  patent application. The `examiner_name` field in the lookup response is
  already in the correct format.
</Tip>

## Use cases

* **Pre-analysis**: Check examiner behavior before choosing a response strategy
* **Interview prep**: High `interview_success_rate` suggests scheduling an examiner interview
* **Workload assessment**: `avg_actions_to_allowance` indicates how many rounds to expect


# Poll Draft Status
Source: https://docs.abigail.app/api-reference/paid/poll-status

api-reference/paid/openapi.json get /v1/openclaw/draft-roa/status/{job_id}

Poll this endpoint to check the progress of an ROA drafting job.

## Status values

| Status        | Meaning                                 | `download_url` present? |
| ------------- | --------------------------------------- | ----------------------- |
| `queued`      | Job is waiting for a worker             | No                      |
| `in_progress` | Job is actively generating the document | No                      |
| `complete`    | Document is ready for download          | Yes                     |
| `failed`      | Job failed (see `error_message`)        | No                      |

## Polling strategy

Poll every 5 seconds. Typical drafting jobs complete in 30-120 seconds.

```python theme={null}
import time
import httpx

def wait_for_draft(base_url, job_id, api_key, timeout=300):
    headers = {"X-API-Key": api_key}
    start = time.time()
    while time.time() - start < timeout:
        resp = httpx.get(
            f"{base_url}/v1/openclaw/draft-roa/status/{job_id}",
            headers=headers,
        )
        data = resp.json()
        if data["status"] == "complete":
            return data["download_url"]
        if data["status"] == "failed":
            raise Exception(f"Draft failed: {data.get('error_message')}")
        time.sleep(5)
    raise TimeoutError("Draft did not complete within timeout")
```

## Download URL

The `download_url` is a signed URL that includes a JWT token. It expires after
**1 hour**. If it expires, re-poll this endpoint to get a fresh URL.

<Note>
  Polling this endpoint is free and not billed.
</Note>


# Authentication
Source: https://docs.abigail.app/authentication

API key creation, usage, and security.

The Abigail API uses two authentication methods:

| Method        | Used for                                 | Header                          |
| ------------- | ---------------------------------------- | ------------------------------- |
| **API Key**   | OpenClaw endpoints (`/v1/openclaw/*`)    | `X-API-Key`                     |
| **Clerk JWT** | Developer portal (`/api/v1/developer/*`) | `Authorization: Bearer <token>` |

## API Key Authentication

All paid endpoints require an API key in the `X-API-Key` header.

### Key format

```
abi_sk_{32_hex_characters}
```

Example: `abi_sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4`

### Using your key

```bash theme={null}
curl -H "X-API-Key: abi_sk_your_key_here" \
  https://api.abigail.app/v1/openclaw/analyze
```

```python theme={null}
import httpx

resp = httpx.post(
    "https://api.abigail.app/v1/openclaw/analyze",
    headers={"X-API-Key": "abi_sk_your_key_here"},
    json={"application_number": "17200011", "office_action_text": "..."}
)
```

### Key lifecycle

1. **Create** a key from [Settings > API Keys](https://abigail.app/settings?tab=api-keys)
2. The raw key is shown **once** -- copy it immediately
3. Only the SHA-256 hash is stored server-side
4. **Revoke** a key anytime from [Settings > API Keys](https://abigail.app/settings?tab=api-keys)
5. Revoked keys are rejected immediately

### Security best practices

<Warning>
  Never commit API keys to source control. Use environment variables or a secrets manager.
</Warning>

* Store keys in environment variables: `ABIGAIL_API_KEY=abi_sk_...`
* Rotate keys periodically
* Use separate keys for development and production
* Revoke keys immediately if compromised

## Error responses

### Missing key

```json theme={null}
{
  "error": true,
  "error_code": "missing_api_key",
  "message": "Missing X-API-Key header.",
  "agent_suggestion": "This endpoint requires an Abigail API key. The user must create one at https://abigail.app and provide it to you."
}
```

### Invalid key

```json theme={null}
{
  "error": true,
  "error_code": "invalid_api_key",
  "message": "API key invalid.",
  "agent_suggestion": "The API key is invalid. Ask the user to generate a new key at https://abigail.app"
}
```

### Revoked key

```json theme={null}
{
  "error": true,
  "error_code": "revoked_api_key",
  "message": "API key revoked.",
  "agent_suggestion": "The API key is revoked. Ask the user to generate a new key at https://abigail.app"
}
```


# Agent Suggestions
Source: https://docs.abigail.app/concepts/agent-suggestions

Every error includes actionable guidance for AI agents.

The Abigail API is designed for consumption by AI agents (OpenClaw, custom LLM workflows).
Every error response includes an `agent_suggestion` field with specific, actionable guidance
that an agent can follow without human intervention.

## Error response format

```json theme={null}
{
  "error": true,
  "error_code": "app_not_found",
  "message": "Application 17200011 not found in USPTO Patent Center.",
  "agent_suggestion": "Application not found. Verify the number format (17200011 or 17/200,011) and check for typos."
}
```

## Fields

| Field              | Type    | Purpose                                               |
| ------------------ | ------- | ----------------------------------------------------- |
| `error`            | boolean | Always `true` for error responses                     |
| `error_code`       | string  | Machine-readable error code for programmatic handling |
| `message`          | string  | Human-readable description                            |
| `agent_suggestion` | string  | Actionable next step for AI agents                    |

## Error codes

| Code                     | HTTP | Meaning                                   |
| ------------------------ | ---- | ----------------------------------------- |
| `app_not_found`          | 404  | Application number not in database        |
| `examiner_not_found`     | 404  | Examiner name not found                   |
| `missing_api_key`        | 401  | No X-API-Key header provided              |
| `invalid_api_key`        | 401  | Key not recognized                        |
| `revoked_api_key`        | 401  | Key has been revoked                      |
| `invalid_download_token` | 401  | Download token expired or invalid         |
| `token_job_mismatch`     | 403  | Download token issued for a different job |

## Agent implementation pattern

```python theme={null}
response = httpx.get(f"{BASE_URL}/v1/openclaw/lookup/{app_number}")

if response.status_code != 200:
    error = response.json()
    code = error.get("error_code")
    suggestion = error.get("agent_suggestion", "")

    if code == "app_not_found":
        # Try normalizing the number
        normalized = app_number.replace("/", "").replace(",", "")
        response = httpx.get(f"{BASE_URL}/v1/openclaw/lookup/{normalized}")
    elif code == "missing_api_key":
        # Prompt user for API key
        return f"I need an API key to proceed. {suggestion}"
    elif code == "revoked_api_key":
        return f"Your API key has been revoked. {suggestion}"
```

The `agent_suggestion` text is written so that an LLM agent can include it directly
in a response to the user.


# Glass Box Transparency
Source: https://docs.abigail.app/concepts/glass-box

Every analysis includes metadata showing how AI decisions were made.

Every response from the `/analyze` endpoint includes a `glass_box` object that provides
full transparency into the AI decision-making process.

## Why Glass Box?

Patent prosecution requires trust. Attorneys need to verify AI-generated analysis before
filing with the USPTO. Glass Box metadata lets you:

* See which AI expert modules participated in the analysis
* Verify that prior art citations were checked against source documents
* Assess confidence levels per expert
* Track model versions for reproducibility
* Measure processing time

## Structure

```json theme={null}
{
  "glass_box": {
    "experts_invoked": ["claim_analyst", "prior_art_mapper", "examiner_profiler"],
    "citations_verified": true,
    "confidence_scores": {
      "claim_analyst": 0.92,
      "prior_art_mapper": 0.87
    },
    "model_versions": {
      "claim_analyst": "claude-sonnet-4-20250514",
      "prior_art_mapper": "claude-sonnet-4-20250514"
    },
    "elapsed_seconds": 12.4
  }
}
```

## Fields

| Field                | Type      | Description                                                   |
| -------------------- | --------- | ------------------------------------------------------------- |
| `experts_invoked`    | string\[] | AI expert modules that ran during analysis                    |
| `citations_verified` | boolean   | Whether prior art citations were verified against source text |
| `confidence_scores`  | object    | Per-expert confidence (0-1 scale)                             |
| `model_versions`     | object    | LLM model version used by each expert                         |
| `elapsed_seconds`    | number    | Total processing time                                         |

## Expert modules

| Expert                 | Role                                                                        |
| ---------------------- | --------------------------------------------------------------------------- |
| `claim_analyst`        | Parses claims, identifies rejected claims, maps rejection bases             |
| `prior_art_mapper`     | Maps prior art references to specific claim limitations                     |
| `examiner_profiler`    | Analyzes examiner behavior patterns (when `include_examiner_intel` is true) |
| `strategy_recommender` | Recommends per-claim response strategies                                    |

## Using Glass Box in your agent

AI agents should check Glass Box data to calibrate trust:

```python theme={null}
result = analyze_office_action(...)
glass_box = result["glass_box"]

# Only proceed with high-confidence analysis
if glass_box["confidence_scores"].get("claim_analyst", 0) < 0.7:
    # Flag for human review
    notify_user("Low confidence analysis -- recommend manual review")

# Verify citations were checked
if not glass_box["citations_verified"]:
    # Citations may be hallucinated
    notify_user("Citations not verified against source documents")
```


# Billing & Rate Limits
Source: https://docs.abigail.app/concepts/rate-limits

Credit-based billing, usage tracking, and rate limits.

The Abigail API uses a **credit-based billing system**. You purchase credits, and
usage is deducted in real-time based on token consumption. LLM usage is never blocked --
only document exports are credit-gated.

## How billing works

1. Purchase a credit package (or receive \$25 welcome credits on signup)
2. Every API call that uses AI consumes tokens (input + output)
3. Token costs are deducted from your credit balance automatically
4. Every response includes balance headers so you can track spending

## Token pricing

| Service Type    | Rate                   |
| --------------- | ---------------------- |
| Standard Input  | \$50.00 per 1M tokens  |
| Standard Output | \$200.00 per 1M tokens |

A typical `/analyze` call processes \~2,000 input tokens and \~1,500 output tokens,
costing approximately \$0.40 per analysis.

### Model multiplier

Your account has a model version setting (default 1.0x) that multiplies base token
prices. Higher-capability models may have higher multipliers.

## Credit packages

| Package      | Price   | Credits | Bonus  |
| ------------ | ------- | ------- | ------ |
| Starter      | \$25    | \$25    | --     |
| Professional | \$100   | \$100   | +\$10  |
| Business     | \$500   | \$500   | +\$75  |
| Enterprise   | \$2,000 | \$2,000 | +\$400 |

Custom amounts are also supported (1:1 credits, no bonus).

New accounts receive **\$25 in welcome credits** to get started.

## Document export pricing

Document exports (DOCX downloads) are **credit-gated** -- the API returns HTTP 402
if your balance is insufficient.

| Document Type | Price   |
| ------------- | ------- |
| OA Response   | \$49.00 |
| IDS           | \$9.00  |
| Form          | \$5.00  |
| Drawing       | \$5.00  |

<Warning>
  Document exports are the only operations that block on insufficient credits.
  All LLM-based operations (analyze, examiner lookup) always complete regardless
  of balance.
</Warning>

## What is free?

These operations are never billed:

* `GET /v1/openclaw/lookup/{app_number}` -- application metadata
* `GET /v1/openclaw/deadlines/{app_number}` -- response deadlines
* `GET /v1/openclaw/draft-roa/status/{job_id}` -- polling draft status
* `GET /v1/openclaw/download/{job_id}` -- downloading a completed DOCX (the draft
  submission is billed, not the download)

## Usage tracking headers

Every response from authenticated endpoints includes these headers:

```
X-Credit-Balance: 142.50
X-Balance-Status: healthy
X-Usage-Requests-Today: 23
X-Usage-Requests-Hour: 5
```

### Balance status thresholds

| Status     | Balance    | Meaning                          |
| ---------- | ---------- | -------------------------------- |
| `healthy`  | > \$25     | Normal operation                 |
| `low`      | $10 -- $25 | Consider purchasing more credits |
| `very_low` | $5 -- $10  | Running low                      |
| `critical` | \< \$5     | Nearly depleted                  |

When balance is `low` or below, responses also include:

```
X-Purchase-Prompt: true
X-Purchase-Message: Your credit balance is low. Purchase more credits to continue using AI features.
```

## Handling 402 responses

When a document export is blocked for insufficient credits:

```json theme={null}
{
  "error": true,
  "error_code": "insufficient_credits",
  "message": "Insufficient credits for OA Response export ($49.00 required).",
  "agent_suggestion": "The user needs to purchase more credits before exporting this document. Current balance is insufficient."
}
```

Your agent should inform the user to purchase credits and retry.

## Rate limits

| Tier                    | Rate                | Burst              |
| ----------------------- | ------------------- | ------------------ |
| Free endpoints          | 60 requests/minute  | 10 requests/second |
| API key (authenticated) | 120 requests/minute | 20 requests/second |

Rate limits are per API key (authenticated) or per IP (free endpoints).

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1708732800
```

### Handling 429 responses

```python theme={null}
import time
import httpx

def call_with_retry(url, headers, json_body, max_retries=3):
    for attempt in range(max_retries):
        resp = httpx.post(url, headers=headers, json=json_body)
        if resp.status_code == 429:
            wait = 2 ** attempt  # 1, 2, 4 seconds
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit exceeded after retries")
```


# Abigail API
Source: https://docs.abigail.app/index

Patent prosecution AI for developers and AI agents.

The Abigail API gives you programmatic access to AI-powered patent prosecution tools.
Analyze office actions, draft response documents, and access examiner intelligence --
all through a single REST API.

## Who is this for?

* **AI agent developers** building patent prosecution workflows (OpenClaw, custom agents)
* **Law firm engineering teams** integrating AI analysis into existing docketing systems
* **Solo practitioners** automating repetitive prosecution tasks

## Endpoint overview

| Endpoint                                     | Auth    | Billing                  | Description             |
| -------------------------------------------- | ------- | ------------------------ | ----------------------- |
| `GET /v1/openclaw/lookup/{app_number}`       | None    | Free                     | Application metadata    |
| `GET /v1/openclaw/deadlines/{app_number}`    | None    | Free                     | Response deadlines      |
| `POST /v1/openclaw/analyze`                  | API key | Token-based              | Office action analysis  |
| `POST /v1/openclaw/draft-roa`                | API key | Token-based + export fee | Draft response document |
| `GET /v1/openclaw/draft-roa/status/{job_id}` | API key | Free                     | Poll draft status       |
| `GET /v1/openclaw/examiner/{name}`           | API key | Token-based              | Examiner intelligence   |
| `GET /v1/openclaw/download/{job_id}`         | Token   | Free                     | Download DOCX           |

## Quick example

```bash theme={null}
# Free: Look up a patent application
curl https://api.abigail.app/v1/openclaw/lookup/17200011

# Paid: Analyze an office action
curl -X POST https://api.abigail.app/v1/openclaw/analyze \
  -H "X-API-Key: abi_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "application_number": "17200011",
    "office_action_text": "Claims 1-5 are rejected...",
    "office_action_type": "CTNF"
  }'
```

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get your API key and make your first call in 2 minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key creation and security best practices.
  </Card>

  <Card title="Glass Box" icon="eye" href="/concepts/glass-box">
    Understand AI transparency metadata in every response.
  </Card>

  <Card title="API Reference" icon="code">
    Full endpoint documentation with interactive playground. See the API Reference tab.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.abigail.app/quickstart

Get your API key and make your first call in 2 minutes.

## 1. Create an account

Sign up at [abigail.app](https://abigail.app) using your email or Google account.
Authentication is handled by Clerk.

## 2. Generate an API key

1. Log in at [abigail.app](https://abigail.app)
2. Go to [Settings > API Keys](https://abigail.app/settings?tab=api-keys)
3. Click **Create API Key** and name it (e.g., "OpenClaw Agent")
4. Copy the key immediately -- it is shown only once

Your key looks like: `abi_sk_a1b2c3d4e5f6...` (39 characters).

<Warning>
  Store your API key securely. It cannot be retrieved after creation.
  If lost, revoke the old key and create a new one.
</Warning>

## 3. Make your first call

Try a free endpoint first (no API key needed):

```bash theme={null}
curl https://api.abigail.app/v1/openclaw/lookup/17200011
```

Then try a paid endpoint with your key:

```bash theme={null}
curl -X POST https://api.abigail.app/v1/openclaw/analyze \
  -H "X-API-Key: abi_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "application_number": "17200011",
    "office_action_text": "Claims 1-5 are rejected under 35 U.S.C. 102(a)(1)...",
    "office_action_type": "CTNF"
  }'
```

## 4. Full workflow

The typical agent workflow is:

```mermaid theme={null}
graph LR
    A[Lookup App] --> B[Analyze OA]
    B --> C[Draft ROA]
    C --> D[Poll Status]
    D --> E[Download DOCX]
```

1. **Lookup** the application to get metadata and examiner name
2. **Analyze** the office action text to get claim-by-claim analysis
3. **Draft ROA** using the analysis\_id and your strategy selections
4. **Poll** the draft job until status is `complete`
5. **Download** the DOCX via the signed URL

## 5. Error handling

Every error response includes an `agent_suggestion` field with actionable guidance
for AI agents:

```json theme={null}
{
  "error": true,
  "error_code": "app_not_found",
  "message": "Application 99999999 not found.",
  "agent_suggestion": "Application not found. Verify the number format (17200011 or 17/200,011) and check for typos."
}
```

Your agent should read `agent_suggestion` and act on it automatically.