Verification Contexts

Pipelines produce better verdicts when they know what you expect to be true. A photograph is easier to authenticate when the pipeline knows the claimed camera, location, and date. A news article is easier to fact-check when the pipeline knows the claimed source URL.

Verification contexts let you supply this claimed metadata — called context keys — as named, reusable sets attached to a project. You reference a context when creating a verification run rather than embedding the same fields in every request.

What is a Context?

A verification context is a named set of key-value pairs saved at the project level. Contexts are reusable: you can attach the same context to many runs without repeating yourself, and you can build a library of contexts that correspond to recurring sources or scenarios.

Example: a context called "Reuters Wire Nov 2024" might contain:

{
  "name": "Reuters Wire Nov 2024",
  "data": {
    "claimed_source": "Reuters",
    "claimed_date": "2024-11-15",
    "claimed_location": "Paris, France"
  }
}

Any run referencing this context will have those claims available to every stage that knows how to use them.

Context Keys by Pipeline

The table below lists the most commonly used context keys and the pipelines that consume them.

Key	Used by pipelines	Required?
`claimed_source`	image pipelines, video pipelines	Optional
`claimed_date`	most pipelines	Optional
`claimed_location`	`verify-image-deep`, `verify-video-full`	Optional
`claimed_speaker`	audio pipelines	Optional
`article_url`	`verify-news-article`	Required if no file
`article_text`	`verify-news-article`	Required if no file
`post_url`	`verify-social-post`	Required if no file
`post_text`	`verify-social-post`	Required if no file
`url`	`verify-url-credibility`	Required
`person_name`	`verify-identity-claim`	Required

Optional keys enrich the analysis when provided — the pipeline will use them if present and proceed without them if not. Required keys will cause the pipeline to return a 422 error if they are absent and no file provides an equivalent signal.

Creating a Context

Create a context by posting to the project's verification-contexts endpoint.

curl -X POST \
  https://api.crowdee.ai/v2/projects/{projectId}/verification-contexts \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reuters Wire Nov 2024",
    "data": {
      "claimed_source": "Reuters",
      "claimed_date": "2024-11-15",
      "claimed_location": "Paris, France"
    }
  }'

Example response:

{
  "id": "ctx_abc123",
  "name": "Reuters Wire Nov 2024",
  "data": {
    "claimed_source": "Reuters",
    "claimed_date": "2024-11-15",
    "claimed_location": "Paris, France"
  },
  "projectId": "proj_abc123",
  "createdAt": "2024-11-15T09:00:00Z"
}

Save the id — you will use it as context_id when creating runs.

Using a Context in a Run

You can attach context to a verification run in two ways: by referencing a saved context by ID, or by passing an inline context object directly in the run request.

curl -X POST \
  https://api.crowdee.ai/v2/projects/{projectId}/verification-runs \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "verify-image-deep",
    "file_ids": ["file_xyz789"],
    "context_id": "ctx_abc123"
  }'

Use a saved context when the same set of claims applies to many runs. The context is snapshotted at run creation time, so later edits to the context do not affect historical runs.

curl -X POST \
  https://api.crowdee.ai/v2/projects/{projectId}/verification-runs \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "verify-image-deep",
    "file_ids": ["file_xyz789"],
    "context": {
      "claimed_source": "AP Photo",
      "claimed_date": "2024-11-14",
      "claimed_location": "Berlin, Germany"
    }
  }'

Use an inline context for one-off runs where the claims are unique. The data is still snapshotted and stored with the run for audit purposes.

Listing Contexts

Retrieve all contexts for a project:

curl https://api.crowdee.ai/v2/projects/{projectId}/verification-contexts \
  -H "X-API-Key: crw_YOUR_API_KEY"

To list all contexts across your entire organization:

curl https://api.crowdee.ai/v2/verification-contexts \
  -H "X-API-Key: crw_YOUR_API_KEY"

Updating and Deleting

Update a context with PUT:

curl -X PUT \
  https://api.crowdee.ai/v2/projects/{projectId}/verification-contexts/{contextId} \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reuters Wire Nov 2024 (revised)",
    "data": {
      "claimed_source": "Reuters",
      "claimed_date": "2024-11-15",
      "claimed_location": "Paris, France",
      "claimed_photographer": "John Doe"
    }
  }'

Delete a context with DELETE:

curl -X DELETE \
  https://api.crowdee.ai/v2/projects/{projectId}/verification-contexts/{contextId} \
  -H "X-API-Key: crw_YOUR_API_KEY"

Updating or deleting a context does not affect already-completed runs. A snapshot of the context data is stored with each run at creation time, preserving the audit trail regardless of future changes to the context.