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

# Smokeball

> Matter and folder import

`provider: "smokeball"` · Import only · Generally available

The Smokeball connector browses matters and their document folders and imports a whole matter or a nested folder into a vault.

> [!NOTE]
>
> US region only, and the scope tier is always `smokeball.us`. Export to Smokeball is not available:
> `supports_export` is `false` in the `providers` array, and an export or `both` transfer returns
> `403`.

## Browsing

Browse with no parameters to list the matters the connected user can reach. Each matter is named by its number and title, and carries a folder reference to the matter's document root, so you can import the whole matter or descend into a subfolder first. Pass `query` to filter matters by text.

```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl "https://api.case.dev/connectors/v1/connections/conn_abc123/browse" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"
```

```json title="Response" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "items": [
    {
      "id": "3f6c2a8e-5b1d-4c7a-9e2f-0a1b2c3d4e5f",
      "name": "2026-0142 — Smith v. Hospital",
      "kind": "matter",
      "container_id": "3f6c2a8e-5b1d-4c7a-9e2f-0a1b2c3d4e5f",
      "browse_ref": {
        "kind": "folder",
        "folder_id": "root",
        "container_id": "3f6c2a8e-5b1d-4c7a-9e2f-0a1b2c3d4e5f"
      }
    }
  ],
  "cursor": "100"
}
```

Smokeball has no search, folder contents, folder links or single-file fetch. Those endpoints answer `422` with `search_not_supported`, `contents_not_supported`, `link_resolve_not_supported` or `fetch_not_supported`, so build your picker on browse.

## Importing a matter

```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X POST https://api.case.dev/connectors/v1/transfer \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "import",
    "connection_id": "conn_abc123",
    "remote": {
      "container_id": "3f6c2a8e-5b1d-4c7a-9e2f-0a1b2c3d4e5f",
      "folder_id": "root",
      "path": "2026-0142 — Smith v. Hospital"
    },
    "vault_id": "vault_abc123"
  }'
```

Everything under the selected folder, at any depth, is imported.

## Change detection

Smokeball has no change feed. Every run lists the whole selected folder again and compares it with the ledger, so additions, updates and deletions are all caught on every run, and unchanged files are not downloaded again. The cost is that each run is a full scan, which matters for large matters and for many synced links on the same account.

Start with one-time imports, or a small number of synced links, and grow from there.

## Rate budget and run capacity

Smokeball allows 5 requests per second (300 per minute). Case.dev paces all Smokeball traffic to that rate, across every connection, run and instance, so a busy import elsewhere can slow browsing for your users.

Each connection runs at most **two** imports at once, whatever started them. A manual transfer while two are active returns `409` with `data.error.code` set to `connection_capacity`. This is not a connection problem: let the user retry once an active import finishes.

## Reconnection

When Smokeball authorization lapses, the connection moves to `reauth_required` and a [`connection.reauth_required`](https://docs.case.dev/connectors/errors#reauthorization-required) event fires. Send the user through the [connect flow](https://docs.case.dev/connectors/oauth.md#reconnecting) again; links resume with their ledgers intact.

## Capabilities at a glance

| | |
| - | - |
| Containers | Matters |
| Browse depth | Folder |
| Change detection | Full relist on every run |
| Export | No |
| Collection | `documents` |
| Scope tier | `smokeball.us` |
| Rate budget | 300 requests/min shared across all Smokeball traffic; 2 concurrent runs per connection |

## Next steps

> [card] [Import & Export](https://docs.case.dev/connectors/transfers.md)
>
> Link mechanics, policies, and progress

> [card] [Errors & Recovery](https://docs.case.dev/connectors/errors.md)
>
> Throttling, reauthorization, and capacity limits

> [card] [All providers](https://docs.case.dev/connectors/providers.md)
>
> Compare against the other supported providers


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.