How to create Custom (Structured) Content in Arc XP

You can create structured content schemas programmatically using the Arc XP Draft API. Schema creation is the only action that is required to be taken via API. After a schema is created, it can be modified to add additional fields from the Data Center UI.

See Structured (Custom) Content in Arc XP to learn more about Structured Content.

This guide walks through a complete schema creation request using POST /draft/v1/schema-type, with a working events schema as the example.

Before you start

You need:

• A valid Arc XP API token with write access to the Draft API
• Your organization’s Arc XP API base URL (i.e., https://api.myorg.arcpublishing.com)
• A clear picture of your schema structure: field names, types, and which fields need search indexing

That last point is the most important one to get right before sending your first request.

Schema fields are immutable

You cannot remove fields, change a field’s data type, make optional fields required, or remove or change search indexing on a field. The API rejects these changes with a 400 SchemaTypeBreakingChangesError, even if the schema has zero records.

Safe changes: adding new fields, updating display names and descriptions, adding search indexing to a previously unindexed field, making required fields optional, are always allowed.

See the Developer Guide for the full list of allowed and disallowed changes.

Plan your schema

Two decisions are hard to reverse: field types and search indexing. Both need to be right when you create the schema.

Field types are permanent once records exist. A field defined as short-text cannot become date-time. If you get this wrong and already have data, you’d need to delete all records before fixing the schema, or start with a new one.

Search indexing has two independent dimensions:

• API search is set with the search property in the request body (fulltext or vector). It makes the field queryable via the Arc XP Content API.
• Editorial search is a separate setting that controls whether the field is searchable inside Data Manager. It’s configured independently, not through the Draft API.

Decide both for every field upfront. Think through which fields editors or developers will want to filter or search on, not just which ones need to be stored.

There’s no cap on how many fields a schema can have. The limit that matters is how many fields you make searchable (indexed). That capacity is a pool shared across all schemas in your org, not a per-schema allowance.

Make the request

Endpoint

POST /draft/v1/schema-type

Authentication uses a Bearer token in the Authorization header.

Request body

A schema requires name, display_name, and fields. The name is the unique machine-readable identifier. Use a lowercase hyphenated slug like calendar-event or staff-profile. It cannot be changed after creation.

Each field requires key and type. Everything else is optional but worth including.

Field types:

Type	Use for
short-text	Titles, labels, short strings
long-text	Descriptions, body copy
date-time	Dates and timestamps (ISO 8601)
geo-point	Location coordinates (lat/lng)

Search indexing (search property):

Value	Behavior
fulltext	Full-text keyword search via Content API
vector	Semantic/embedding search via Content API
(omit)	Field is stored but not queryable via search

cURL example

This creates an events schema with four fields: a required title with fulltext search, an optional description, a required date, and an optional location.

curl -X POST "https://api.{YOUR_ORG}.arcpublishing.com/draft/v1/schema-type" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "calendar-event",
    "display_name": "Calendar Event",
    "description": "Schema for event listings such as concerts, conferences, and local happenings.",
    "fields": [
      {
        "key": "title",
        "display_name": "Event Title",
        "description": "Name of the event",
        "type": "short-text",
        "is_required": true,
        "search": "fulltext"
      },
      {
        "key": "description",
        "display_name": "Description",
        "description": "Full event description visible to readers",
        "type": "long-text",
        "is_required": false
      },
      {
        "key": "event_date",
        "display_name": "Event Date",
        "description": "Start date and time of the event",
        "type": "date-time",
        "is_required": true
      },
      {
        "key": "venue_location",
        "display_name": "Venue Location",
        "description": "Coordinates of the event venue",
        "type": "geo-point",
        "is_required": false
      }
    ]
  }'

Replace {YOUR_ORG} with your organization identifier and {YOUR_API_TOKEN} with a valid token.

Understand the response

A successful request returns 201 Created with the full schema object:

{
  "name": "calendar-event",
  "display_name": "Calendar Event",
  "description": "Schema for event listings such as concerts, conferences, and local happenings.",
  "schema_version": 1,
  "created_at": "2026-06-26T12:00:00.000Z",
  "updated_at": "2026-06-26T12:00:00.000Z",
  "fields": [
    {
      "key": "title",
      "display_name": "Event Title",
      "description": "Name of the event",
      "type": "short-text",
      "is_required": true,
      "search": "fulltext"
    },
    {
      "key": "description",
      "display_name": "Description",
      "description": "Full event description visible to readers",
      "type": "long-text",
      "is_required": false
    },
    {
      "key": "event_date",
      "display_name": "Event Date",
      "description": "Start date and time of the event",
      "type": "date-time",
      "is_required": true
    },
    {
      "key": "venue_location",
      "display_name": "Venue Location",
      "description": "Coordinates of the event venue",
      "type": "geo-point",
      "is_required": false
    }
  ]
}

schema_version starts at 1 and increments with each PATCH update. created_at and updated_at are system-managed and read-only.

Common errors

400: Invalid request A required property is missing, a field type is not recognized, or the schema exceeds its searchable (indexed) field capacity. Check the error_message in the response for specifics.

409: Conflict A schema with that name already exists in your org. Schema names are unique per organization. Use the existing schema, or choose a different name.

Verify the schema was created

Fetch the schema by name to confirm it looks right:

curl "https://api.{YOUR_ORG}.arcpublishing.com/draft/v1/schema-type/calendar-event" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

To list all schemas in your org:

curl "https://api.{YOUR_ORG}.arcpublishing.com/draft/v1/schema-type" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"