Skip to content

items.md

Latest commit

 

History

History
97 lines (68 loc) · 5.54 KB

items.md

File metadata and controls

97 lines (68 loc) · 5.54 KB

Submit Items API

Send Items to Coop for automated rule evaluation. Every time you submit an item, Coop runs it through all your configured Proactive Rules.

Submit items when they are created, edited, reported, or otherwise need to be re-evaluated. You should also submit items retroactively if you configure new rules after launch. To support Coop fetching Items and their attributes on demand, see the Partial Items API.

Endpoint

POST /api/v1/items/async/

Authentication: X-API-KEY header. See API Keys & Authentication.

Request

{
  "items": [
    {
      "id": "unique-item-id-123",
      "typeId": "your-item-type-id",
      "data": {
        "fieldName1": "value1",
        "fieldName2": 123
      }
    }
  ]
}

You can submit multiple items in a single request by including additional objects in the items array. All processing is asynchronous.

Request body fields

Field Type Required? Description
items Array Required One or more items to submit
items[].id String Required Your unique identifier for this item
items[].typeId String Required The Coop Item Type ID for this item, as configured in the dashboard
items[].data Object Required The item payload. Fields must match the schema defined for the Item Type
items[].data.images Array Optional Array of URL strings. Triggers automated HMA image hashing.
items[].typeVersion String Optional Version string for schema versioning
items[].typeSchemaVariant String Optional Schema variant. Valid values: "original" or "partial"

Formatting data fields

The shape of data must match your Item Type's schema. Common field types:

Field type Format
String Plain string value
Number JSON number
Boolean true or false
Image / Audio / Video URL string pointing to the media
Geohash Base-32 geohash string
Datetime ISO 8601 string (e.g. "2024-01-15T10:30:00.000Z")
Related Item { "id": "...", "typeId": "..." } object

Media access

All media fields (image, audio, video) are submitted as URL references. Coop does not upload or store media content directly.

When an item is submitted, Coop fetches each media URL at that time to run signal processing (HMA hashing, Content Safety analysis, etc.). Media is not re-fetched when a moderator opens the job; instead, the browser loads it directly from the original URL at review time.

Fetches are unauthenticated GET requests. Coop does not forward your API key or any credential to the media URL.

For private or access-controlled media, use pre-signed URLs (e.g. S3 pre-signed URLs). Because the browser loads media directly at review time—potentially hours or days after submission—pre-signed URLs must remain valid for the entire window during which a job could sit in a queue, not just long enough for submission-time signal processing.

Response

Status Meaning
202 Accepted Items received and queued for rule evaluation
400 Bad Request Validation failure; see Errors
401 or 403 Authentication failure

See Errors for the full error response format.

Automated Image Hashing

If the data object for an item contains an images field consisting of an array of URL strings, Coop will automatically:

  1. Fetch the image content from the provided URLs.
  2. Compute perceptual hashes for each image.
  3. Check these hashes against all HMA Matching Banks configured for your organization.
  4. Add the resulting HMA signals to the item for evaluation against your Automated Rules.

Notes

  • Asynchronous Processing: This endpoint is designed for high-volume asynchronous processing. Submissions are enqueued in Redis (via BullMQ) and processed by background workers.

  • Immediate Results: If your implementation strictly requires synchronous processing (receiving rule results in the same HTTP response), use the legacy POST /api/v1/content/ endpoint. Note that the legacy endpoint does not support batched submissions or automated HMA image hashing.

  • Action Callbacks: If a rule matches and triggers an action, Coop sends a POST request to your action callback endpoint.

  • Basic Concepts: For background on Item Types and how items are identified in Coop, see Basic Concepts.