AI Power Ups

Menu

Contents

Research and reading · SearchApi, Serper and official legal sources

legal.search

Discover US case law or EU legal sources with source identifiers and links. US court groups and year ranges apply to case-law discovery. EU source identity is verified where the original is accessible. Search results are source records, not a legal opinion; use legal.read for the original text.
Operation
POST /v1/capabilities/legal.search/execute
operationId
executeLegalSearch
Typical credits
4
Search deadline
40 s server-side
Paging
page
Availability
ConfiguredChecked 2026-09-23 21:02 UTC
Cost basis: US discovery: $0.004 per SearchApi page. EU discovery: actual Serper credits × $0.001, plus actual Firecrawl credits × $0.005 when an original requires retrieval fallback. Direct official sources and cached details are free. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

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

Request fields of legal.search
FieldTypeRequiredDefaultConstraints and description
searchobject | objectyes
search.jurisdictionwhen jurisdiction = "us""us"yes
search.querywhen jurisdiction = "us"stringyesmin length 1, max length 500
search.courtswhen jurisdiction = "us""all" | "federal" | "state"no"all"
search.from_yearwhen jurisdiction = "us"integernomin 1600, max 2100
search.to_yearwhen jurisdiction = "us"integernomin 1600, max 2100
search.jurisdictionwhen jurisdiction = "eu""eu"yes
search.querywhen jurisdiction = "eu"stringyesmin length 1, max length 500
search.kindwhen jurisdiction = "eu""judgment" | "legislation" | "opinion"no
search.languagewhen jurisdiction = "eu""BG" | "CS" | "DA" | "DE" | "EL" | "EN" | "ES" | "ET" | "FI" | "FR" | "GA" | "HR" | "HU" | "IT" | "LT" | "LV" | "MT" | "NL" | "PL" | "PT" | "RO" | "SK" | "SL" | "SV"no"EN"
numintegerno3min 1, max 10
  • 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.

  • from_year must not exceed to_year.

Examples

US privacy decisions

curl
curl -s -X POST https://api.powerups-ai.store/v1/capabilities/legal.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"search":{"jurisdiction":"us","query":"privacy publication truthful information","courts":"federal"},"num":3}'

EU right to be forgotten

curl
curl -s -X POST https://api.powerups-ai.store/v1/capabilities/legal.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"search":{"jurisdiction":"eu","query":"right to be forgotten","kind":"judgment","language":"EN"},"num":3}'
No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

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 LegalSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of legal.search
KeyTypePresenceNote
identifierstringalways
sourcestringalways
source_classstringalways
languagestringwhen the source has it
eclistringwhen the source has itEU judgments.
document_kindstringwhen the source has it
full_textobjectwhen the source has it{ capability: "legal.read", params }, a typed next request.

Caveats

  • Records carry no snippet.
  • A stored candidate without details returns 410 session_expired.

Follow-ups

  • Paging: Provider page number; more fetches the next page from the source. 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 (LegalSearchUpdateParams).
  • Record actions:
    • details: Source identity, metadata and an exact legal.read request when supported.
  • Detail behaviour: Stored at search time; details is free and never calls the provider. details returns the stored candidate at no charge.
record action
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"}'

Record detail objects of this capability 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:

TypeScript (openapi-fetch)
const { data, error } = await client.POST("/v1/capabilities/legal.search/execute", {
  body: {
    "search": {
      "jurisdiction": "us",
      "query": "privacy publication truthful information",
      "courts": "federal"
    },
    "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);