Resources · Tutorials

Tutorials

Hands-on walkthroughs for common builds. They use the live API and MCP tools with a key from app.data.co; you can also follow along against the demo records in each dataset's preview.

Developer quickstart Code examples

Tutorial 1

A legal research agent that cites its sources

Connect an MCP-capable agent to case law, and make it answer only from retrieved opinions with citations.

1
Connect
Add the Data.co MCP server at https://api.data.co/mcp to your client with a key scoped to mcp:invoke, legal:read and datasets:read. Confirm the connection with tools/list.
2
Check the catalog
Have the agent call list_legal_datasets once per session and note each dataset's access status, so it knows what it can and cannot search.
3
Search
Have the agent call search_case_law with the user's question and a jurisdiction filter.
4
Ground
Fetch the top results with get_legal_document and pass opinion text — not AI summaries — as evidence.
5
Cite
Require a citation and source URL for every claim, and refuse when retrieval returns nothing relevant.
6
Respect restrictions
Read access_restrictions on each result. Never cite a record marked demo or derived as authority, and do not bulk-copy results where the license forbids it.

Tutorial 1 · Prompt

A system prompt that enforces grounding

A starting point. Adapt it to your agent framework; the important parts are the refusal rule and the treatment of AI summaries and demo records.

system.txt

You answer legal research questions using only documents
returned by the Data.co tools.

1. Call search_case_law with the question and any jurisdiction
   or date the user gives.
2. Call get_legal_document for the most relevant results.
3. Quote opinion text, not the "enrichment" block. Enrichment is
   AI-generated by the provider and is not citable as authority.
4. Cite every claim with the citation, court, date and
   canonical_url of the record it came from.
5. If a result's access_restrictions include DEMO, say the data
   is a demo placeholder and do not rely on it.
6. If nothing relevant is retrieved, say so. Do not answer from
   memory. This is research assistance, not legal advice.

Illustrative example · final API surface documented in /docs

Tutorial 2

Add case-law retrieval to an existing RAG app

Use the REST API as one more retriever alongside your internal documents.

1
Query
Call POST /v1/legal/search with the user query and any jurisdiction or date filters; read meta.next_cursor if you need more.
2
Normalize
Map each record to your chunk format, keeping provenance fields.
3
Rank
Merge with your internal results; label external sources clearly in the UI.
4
Attribute
Show court, date, citation and a link to the canonical source for each external passage.
5
Store references, not copies
Cache record ids and provenance rather than bulk copies of text, unless the dataset's license allows storage. Re-fetch by id when you need the full opinion.

Tutorial 2 · Code

A retriever that keeps provenance

retriever.py

import os, requests

def dataco_retrieve(query: str, k: int = 8) -> list[dict]:
    r = requests.post(
        "https://api.data.co/v1/legal/search",
        headers={"Authorization": f"Bearer {os.environ['DATACO_API_KEY']}"},
        json={"q": query, "limit": k},
        timeout=15,
    )
    env = r.json()
    if env["error"]:
        return []  # log env["error"]["code"]; fall back to internal results
    return [
        {
            "text": rec["snippet"],
            "source": "data.co",
            "id": rec["id"],
            "citation": (rec["citations"] or [None])[0],
            "court": rec["court"],
            "date": rec["date"],
            "license": rec["provenance"]["licenseId"],
            "demo": rec["demo"],
        }
        for rec in env["data"]
    ]

Illustrative example · final API surface documented in /docs

Try the filters now.

Every dataset page has an interactive preview over synthetic demo records with the same filters the API accepts.

Court opinions preview

Testing

How to check that grounding works

Build a small evaluation set before you ship: questions with known answers in specific cases, questions with no good answer in the corpus, and questions outside the corpus altogether, such as statutes or regulations, which the legal datasets do not contain. A grounded agent should cite the right cases for the first group and decline the other two.

Check every citation in the output against the record it claims to come from, using the record id. Log the request ids of the tool calls behind each answer so a reviewer can reconstruct what the agent saw.

FAQ

Questions buyers ask

Can I run these tutorials today?

Yes. Create a key at app.data.co and run them against live LAW.co records over REST or MCP. The dataset previews on this site use synthetic demo records.

Why ground on opinion text rather than summaries?

Opinion text is the court's own language and can be cited. Summaries are AI-generated by the provider, useful for triage, but not authority.

Why do search results vary between runs?

LAW.co's current upstream search randomly samples up to 50 results, and a warning in meta.warnings says so. Treat it as a retrieval aid, not an exhaustive search.

Can the agent resolve a citation the user types?

Not yet. get_citation returns a structured unsupported_operation error because LAW.co has no citation resolver. Search by the case name or citation text instead.