How to query (search) structured content records via the Content API

The Content API exposes SCT records through three read-only endpoints: one for listing records by schema type, one for fetching a single record by ID, and one for fetching a single record by URL. This is the read path for headless and hybrid implementations. Think server-rendered sites, mobile apps, or any client that fetches structured content outside of PageBuilder.

For the PageBuilder content source approach, see How to Embed Structured Content Records in PageBuilder.

Before you start

You need:

• Your Arc XP organization ID (org)
• A bearer token with Content API read access
• A schema with at least one published record
• The schema name (e.g., events). This is the identifier from the schema definition, not its display name

Records only appear in the Content API after they are published and circulated to a website. A query only returns records circulated to the website you pass. Draft records stay in the Draft API.

How records appear in responses

A Content API response for an SCT record includes two parts: server-assigned metadata and the field values from your schema.

{
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "schema_name": "events",
  "created_date": "2026-05-01T14:30:00Z",
  "first_publish_date": "2026-05-02T10:00:00Z",
  "publish_date": "2026-06-10T09:15:00Z",
  "websites": {
    "the-daily-planet": { "website_url": "/events/arc-xp-summit-2026/" }
  },
  "schema_content": {
    "title": "Arc XP Summit 2026",
    "event-date": "2026-09-15T09:00:00Z",
    "location": {
      "lat": 38.9072,
      "lon": -77.0369
    },
    "ticket-url": "https://example.com/tickets"
  }
}

The schema_content object contains the field values defined in your schema. Optional fields that were never given a value are absent.

Records with references

A schema can declare reference fields (see Reference fields). In the Content API the reference is already resolved: the field holds the referenced document in Arc XP Native Specification (ANS) format, not a pointer, so a record and the content it points at arrive in one response.

{
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "schema_name": "events",
  "schema_content": {
    "title": "Arc XP Summit 2026",
    "venue": {
      "_id": "PLVVMP6DQZDQ3EU3LZ7HKQZCJE",
      "type": "schema",
      "schema_name": "venues",
      "schema_content": { "name": "Walter E. Washington Convention Center", "city": "Washington" }
    },
    "hero_image": {
      "_id": "4XK6OWIZNNF3RKKBYWT7ZY5QZQ",
      "type": "image",
      "url": "https://cloudfront-us-east-1.images.arcpublishing.com/…/summit.jpg",
      "caption": "Opening keynote"
    }
  }
}

What to expect:

• One level deep. A reference inside a resolved target (the venue’s own city reference, say) is left as it was stored, a node shaped {"type": "reference", "referent": {…}}. Fetch it separately if you need it.
• Unresolved references stay as nodes. If the target does not exist, has been deleted, or has no published copy yet, the field keeps that same reference node instead of the content. Check type === "reference" before reading a field as content.
• The copy is as of the record’s last publish. Content API serves what was resolved when the referencing record was indexed. When the target changes, the record shows the new version only after it is republished.
• Reference fields are not queryable. They take no index, so q= cannot filter on anything inside a resolved reference. Put the values you need to search on in indexed fields of the record itself.

Fetch a list of records

curl -G "https://api.{org}.arcpublishing.com/content/v5/search/schemas/" \
  -H "Authorization: Bearer {your-token}" \
  --data-urlencode "schema_name=events" \
  --data-urlencode "website={your-site}" \
  --data-urlencode "size=25" \
  --data-urlencode "page=1"

Replace {org} with your organization ID and {your-site} with your site identifier.

The response wraps the current page of records in data:

{
  "data": [
    { ... },
    { ... }
  ]
}

If no record matches, the API returns a 404.

Query parameters:

Parameter	Type	Description
schema_name	string	Required. Schema identifier (e.g., events).
website	string	Required. Your site identifier.
size	integer	Records per page. Default 25, max 50.
page	integer	Page number, from 1 to 100.
sort	string	first_publish_date:desc (default) or publish_date:desc.
q	string	Structured filter expression: field:value pairs, whitespace-separated, implicit AND. Not a free-text search box.
include / exclude	string	Comma-separated list of fields to return or omit (e.g. schema_content.title). Use one or the other.

Fetch a single record by ID

curl -G "https://api.{org}.arcpublishing.com/content/v5/search/schemas/by-id/" \
  -H "Authorization: Bearer {your-token}" \
  --data-urlencode "id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --data-urlencode "schema_name=events" \
  --data-urlencode "website={your-site}"

Returns the record in data as a single object. You get a 404 if the record does not exist, hasn’t been published yet, or isn’t circulated to the website.

Fetch a single record by URL

curl -G "https://api.{org}.arcpublishing.com/content/v5/search/schemas/by-url/" \
  -H "Authorization: Bearer {your-token}" \
  --data-urlencode "url=/events/arc-xp-summit-2026/" \
  --data-urlencode "schema_name=events" \
  --data-urlencode "website={your-site}"

Returns the record circulated at that URL on the website.

Filtering with indexed fields

Only fields with a search_settings.retrieval array set in the schema can be used in q.

q is a structured filter expression: field:value pairs, whitespace-separated, implicit AND. That supports equality, range, and geo-distance queries against any field with search_settings.retrieval set:

• String equality: schema_content.category:"music"
• Number or boolean equality: schema_content.paid:true
• Range, inclusive: schema_content.event_date:[2026-07-11 TO 2026-07-13]
• Range, exclusive: schema_content.venue_capacity:{100 TO 500}
• Open-ended range: schema_content.event_date:[2026-07-11 TO *]
• Geo distance: schema_content.location_geo:33.77,-84.37,8km

Valid retrieval index kinds: keyword, geo, range. Which kind is valid depends on the field’s type; see Developer Guide for the full type-to-kind table. Range syntax only works on a field whose retrieval array is ["range"].

To see which fields are indexed, fetch your schema definition:

curl "https://api.{org}.arcpublishing.com/draft/v1/schema-type/events" \
  -H "Authorization: Bearer {your-token}"

Any field with a search_settings.retrieval array is queryable via the Content API. A field with only search_settings.editorial set is searchable in Data Manager but invisible to this API.

Plan indexed fields before writing data

Adding search indexing to a field is allowed at any time. Removing or changing it is a breaking change.

Examples

Fetch the latest events

curl -G "https://api.{org}.arcpublishing.com/content/v5/search/schemas/" \
  -H "Authorization: Bearer {your-token}" \
  --data-urlencode "schema_name=events" \
  --data-urlencode "website={your-site}" \
  --data-urlencode "sort=publish_date:desc" \
  --data-urlencode "size=10"

Returns the 10 most recently published events.

Filter events by category

curl -G "https://api.{org}.arcpublishing.com/content/v5/search/schemas/" \
  -H "Authorization: Bearer {your-token}" \
  --data-urlencode "schema_name=events" \
  --data-urlencode "website={your-site}" \
  --data-urlencode 'q=schema_content.category:"music"' \
  --data-urlencode "size=10"

Filters to records where category equals "music". Requires category to have search_settings: { "retrieval": ["keyword"] } in the schema.

Combine filters

curl -G "https://api.{org}.arcpublishing.com/content/v5/search/schemas/" \
  -H "Authorization: Bearer {your-token}" \
  --data-urlencode "schema_name=events" \
  --data-urlencode "website={your-site}" \
  --data-urlencode 'q=schema_content.category:"music" schema_content.event_date:[2026-07-11 TO *]'

Returns music events from July 11, 2026 onward. Requires event_date to have search_settings: { "retrieval": ["range"] } in the schema.

Fetch a specific record

Get the document_id from a list response, or store it when the record is created via the Draft API.

curl -G "https://api.{org}.arcpublishing.com/content/v5/search/schemas/by-id/" \
  -H "Authorization: Bearer {your-token}" \
  --data-urlencode "id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --data-urlencode "schema_name=events" \
  --data-urlencode "website={your-site}"

Pagination

Use size (up to 50) and page (up to 100) to walk through results.

# Page 1
?schema_name=events&website=my-site&size=50&page=1

# Page 2
?schema_name=events&website=my-site&size=50&page=2

A page past the last result returns a 404.