legal.read

Request

Body of POST /v1/capabilities/legal.read/execute, JSON, validated against the LegalReadRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

• Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

• An invalid U.S. Reports identifier is refused before any fetch.

Examples

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/legal.read/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"document":{"source":"eurlex","celex":"62012CJ0131","language":"EN"},"num":3}'

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/legal.read/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"document":{"source":"us_reports","item_id":"usrep532514"},"num":3}'

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/legal.read/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"document":{"source":"historical","work_id":"warren-brandeis-right-to-privacy-1890"},"num":3}'

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the LegalReadRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Caveats

• more continues the same document; source access failures are reported as provider_error, never replaced with text.

Follow-ups

• Paging: Whole result set held in the session; more is served locally and costs nothing. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
• Update: Re-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (LegalReadUpdateParams).
• Record actions:
  • details: The complete selected text chunk with source references and attribution.
• Detail behaviour: Stored at search time; details is free and never calls the provider. details returns the complete stored text chunk at no charge.

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Other record detail objects are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

const { data, error } = await client.POST("/v1/capabilities/legal.read/execute", {
  body: {
    "document": {
      "source": "eurlex",
      "celex": "62012CJ0131",
      "language": "EN"
    },
    "num": 3
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);