Quickstart

This walkthrough makes a legal search, inspects the ranked results, and retrieves the complete source behind the first result.

Before you begin

You need an API key from an active plan or an invite-only evaluation. Create one from API access, store it in a server-side secret manager, and expose it to your local shell only for this walkthrough:

export PI_API_KEY="pi_live_…"

Never put a live key in frontend JavaScript, a mobile bundle, a public repository, or an AI prompt.

1. Search legal sources

curl --request POST \
  --url https://api.pravenintelekt.com/v1/search \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $PI_API_KEY" \
  --max-time 60 \
  --data '{
    "query": "Давностен срок при непозволено увреждане",
    "source_types": [
      "bulgarian_laws_regulations",
      "high_courts_cases"
    ],
    "max_results": 10
  }'

The response contains a ranked results array. Each result includes an opaque collection value and a document_id. Keep both values together; they form the document identifier used by the retrieval endpoint.

{
  "query": "Давностен срок при непозволено увреждане",
  "result_count": 10,
  "results": [
    {
      "document_id": "…",
      "collection": "legal_documents",
      "type": "Закон",
      "title": "Закон за задълженията и договорите",
      "excerpts": []
    }
  ]
}

2. Retrieve the complete document

URL-encode both query parameters when they come from a response:

curl --get \
  --url https://api.pravenintelekt.com/v1/documents \
  --header "X-API-Key: $PI_API_KEY" \
  --data-urlencode "document_id=…" \
  --data-urlencode "collection=legal_documents"

Document retrieval consumes a separate retrieval unit. The response includes ordered elements for article- or paragraph-level rendering when structural data is available.

3. Check usage

curl --url https://api.pravenintelekt.com/v1/usage \
  --header "X-API-Key: $PI_API_KEY"

Track usage before batch workloads instead of waiting for a monthly_quota_exceeded response.

Next steps

• Let the API select source families by omitting source_types.
• Discover filter values through the catalog endpoints in Search.
• Generate a typed TypeScript or Python client.
• Add retry handling from Errors and limits.