Resources

Authentication: JWT | API Key

Resources represent individual content items stored within collections. Each resource maintains a complete revision history, enabling version control and content rollback capabilities. A resource's structure is governed by the schema of the collection it belongs to.

Resources enable:

Content Management - store and organize structured content items
Version Control - track content changes through revisions with automatic numbering
Schema Validation - enforce data structure through the collection's schema
Localization Support - manage multilingual content with locale-specific data
Reference Management - establish relationships between content items

Learn more about related resources:

Collections API - manage collections that contain resources
Components API - manage reusable component schemas embedded in collection schemas via nested fields
Versions API - manage schema versions for validation
Fields API - define content structure and validation rules
Revisions API - manage resource revision history and version control

Path Parameters

Name
:env
Type
string
Description
Unique identifier of the environment
Name
:collection
Type
string
Description
Unique identifier of the collection
Name
:resource
Type
string
Description
Unique identifier of the resource

Use /v1/:env/collections/:collection_key/resources/ to manage resources stored in a collection.

Resource Object

Name
key
Type
string
Description
Unique identifier for the resource within the system.
Name
name
Type
string
Description
Optional human-readable name.
Name
folder
Type
string
Description
Key of the collection this resource belongs to.
Name
content_type
Type
string
Description
Always "document" for resources.
Name
external_id
Type
string
Description
Optional external identifier for the resource. Allowed characters: a-z A-Z 0-9 - _ / ., max 255 characters. Set during creation via POST or PUT upsert. null if not set.
Name
created_at
Type
datetime
Description
Timestamp when the resource was created, in ISO 8601 format.
Name
resource_owner
Type
string
Description
Key of the parent resource (strict-reference collections only).
Name
current_revision
Type
string
Description
Key of the currently published revision, or null for drafts.
Name
vectors_size
Type
integer
Description
Size of stored vector embeddings in bytes. Used for vector storage billing.

Content Structure

Resources follow the schema of the collection they belong to. The data structure is defined by the collection's current schema version and must include all required fields. Collections support draft mode ("mode": "draft") and validation toggles.

Localization

Localizable fields accept objects with locale codes as keys:

{
    "title": {
        "en": "English Title",
        "es": "Título en Español",
        "fr": "Titre en Français"
    }
}

References and Relations

Reference fields link to a single resource in the specified collection (which can be the same collection or another collection).
Relation fields can link to multiple resources in the specified collection.
Values use the format folder_key::resource_key for both references and relations.
Strict-reference collections require resource_owner to be set to the parent resource key during creation.

Data Limits

Maximum data size per revision: 1MB
Vector embeddings (when enabled by your schemas) consume vector storage. When a billable limit is reached, the API responds with 402: Free-plan organizations receive plan_exhausted (with axis set to writes or vector_storage) once that axis is exhausted; paid organizations receive spend_cap_reached when the spend cap is hit.

Revision Management

Each resource maintains a complete revision history. For detailed revision management:

See Revisions API for creating, retrieving, and managing revisions
New revisions are automatically created when resource content is updated
The current_revision field always points to the latest active revision
Use Resource Data to fetch the JSON payload of the current revision

GETapi.foxnose.net/v1/:env/collections/:collection/resources/

List Resources

Retrieves all resources in the specified collection.

Success Response: 200 OK

Query Parameters

Name
status
Type
string
Description
Filter by publication state.
- published – only resources with a current revision
- draft – resources without a published revision
Name
created_at
Type
datetime
Description
Filter by creation date.
- Operators: exact, gt, lt, gte, lte
Name
content_type
Type
string
Description
Filter by content type (currently always "document").
Name
resource_owner
Type
string
Description
Return resources owned by the specified parent resource key (strict-reference collections).
Name
key__in
Type
string
Description
Comma-separated list of resource keys to return (truncated to the API page size if too many values are provided).
Name
external_id
Type
string
Description
Find a resource by its external identifier. Returns only the resource with the matching external_id in this collection, or an empty list if none matches.
Name
limit
Type
integer
Description
Maximum number of results to return. Default: 100.
Name
offset
Type
integer
Description
Number of results to skip for pagination.

Ordering

Name
created_at
Type
datetime
Description
Order by creation date.
- ?ordering=created_at – oldest first
- ?ordering=-created_at – newest first

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to view resources.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- environment_not_found - the specified environment does not exist
- collection_not_found - the specified collection does not exist

Request

GET

/v1/:env/collections/:collection/resources/

curl https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

Response

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "8m3n7k2p",
            "name": "Welcome Post",
            "folder": "6b4qd369",
            "content_type": "document",
            "external_id": null,
            "created_at": "2025-06-15T10:30:00.000000-05:00",
            "resource_owner": null,
            "current_revision": "9q5r8t1w",
            "vectors_size": 0
        },
        {
            "key": "4j6h9l3s",
            "name": "Second Post",
            "folder": "6b4qd369",
            "content_type": "document",
            "external_id": null,
            "created_at": "2025-06-14T14:20:00.000000-05:00",
            "resource_owner": null,
            "current_revision": "2x7z5v8c",
            "vectors_size": 0
        }
    ]
}

POSTapi.foxnose.net/v1/:env/collections/:collection/resources/

Create Resource

Creates a new resource in the specified collection. The resource structure must conform to the collection's schema.

Success Response: 201 Created when wait=true, or 202 Accepted when wait=false.

Query Parameters

Name
external_id
Type
string
Description
Optional external identifier to assign to the resource. Allowed characters: a-z A-Z 0-9 - _ / ., max 255 characters.
Name
wait
Type
bool
Default
default:true
Description
When false, the API queues storage tasks and responds immediately with 202 Accepted. When true, the response waits for storage completion and returns 201 Created.

Request Body

Name
data
Type
object
Required
required
Description
The content data structured according to the collection's schema.
Name
name
Type
string
Default
default:null
Description
Optional human-readable resource name (1-255 characters). Omit or set to null to leave the name blank.
Name
resource_owner
Type
string
Description
Required when the collection inherits strict references. Provide the parent resource key from the parent collection.
Name
mode
Type
string
Default
default:"instant"
Description
Creation mode:
- instant – validate data and publish immediately
- draft – create a draft revision
Name
validate_data
Type
boolean
Default
default:true
Description
When false, skip schema validation. Only allowed when mode is draft.

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to create resources.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- environment_not_found - the specified environment does not exist
- collection_not_found - the specified collection does not exist
Name
409 Conflict
Description
A resource with the specified external_id already exists in this collection.
- external_id_conflict - the provided external_id is already in use; use the PUT upsert endpoint to update existing resources by external_id
Name
402 Payment Required
Description
A billable limit was reached (billing blocks are reported as 402, not 429).
- plan_exhausted - Free plan: the writes or vector_storage axis is exhausted (body includes axis, window_resets_at, upgrade_url)
- spend_cap_reached - paid plan: the spend cap was reached (body includes cap_usd, cycle_resets_at, raise_cap_url)
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - data validation errors against schema
- resource_owner_required - resource owner required for strict reference collections
- resource_owner_not_found - specified resource owner does not exist
- json_size_exceeded - data size exceeds 1MB limit
- plan_limit_exceeded - resource limit for current plan exceeded
- localizable_data_should_be_object - localizable fields must be objects

Request

POST

/v1/:env/collections/:collection/resources/

curl https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "data": {
        "title": {
            "en": "Welcome to Our Blog",
            "es": "Bienvenidos a Nuestro Blog"
        },
        "content": {
            "en": "This is our first blog post...",
            "es": "Esta es nuestra primera entrada..."
        },
        "published": true,
        "author": "john_doe"
    }
}'

Response

{
    "key": "8m3n7k2p",
    "name": "Welcome Post",
    "folder": "6b4qd369",
    "content_type": "document",
    "external_id": null,
    "created_at": "2025-06-16T15:30:01.514282-05:00",
    "resource_owner": null,
    "current_revision": "9q5r8t1w",
    "vectors_size": 0
}

PUTapi.foxnose.net/v1/:env/collections/:collection/resources/?external_id=<value>

Upsert Resource

Creates or updates a resource identified by external_id. If no resource with the given external_id exists in the collection, a new resource is created with its first revision. If one already exists, a new revision is created for the existing resource.

This endpoint is useful for syncing content from external systems where each item has a stable identifier.

Success Responses:

201 Created – new resource created with the first revision
200 OK – new revision created for the existing resource
202 Accepted – request accepted for async processing (when wait=false)

Query Parameters

Name
external_id
Type
string
Required
required
Description
Unique external identifier for the resource within this collection. Allowed characters: a-z A-Z 0-9 - _ / ., max 255 characters.
Name
wait
Type
bool
Default
default:true
Description
When false, the API queues processing and responds immediately with 202 Accepted. When true, the response waits for completion.

Request Body

Name
data
Type
object
Required
required
Description
The content data structured according to the collection's schema.
Name
name
Type
string
Description
Human-readable resource name (1–255 characters). On update, only applied if provided; otherwise the current name is kept.
Name
mode
Type
string
Default
default:"instant"
Description
Revision mode:
- instant – publish the revision immediately
- draft – create a draft revision
Name
resource_owner
Type
string
Description
Parent resource key (strict-reference collections only). Only used during creation; ignored on update.
Name
validate_data
Type
boolean
Default
default:true
Description
When false, skip schema validation. Only allowed when mode is draft.

Update Behavior

When updating an existing resource:

The previous published revision is automatically unpublished
Draft revisions (when mode is draft) do not change the resource's current_revision
name is updated only if provided in the request body
resource_owner is not changed
external_id is not changed

Errors

Name
403 Forbidden
Description
Insufficient permissions.
- permission_denied - insufficient permissions to perform this action
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- external_id_required - external_id query parameter is missing
- data_validation_error - external_id has invalid format, name is empty or longer than 255 characters, or data failed schema validation
- resource_owner_required - resource owner required for strict reference collections
- resource_owner_not_found - specified resource owner does not exist
- json_size_exceeded - data size exceeds 1MB limit
- plan_limit_exceeded - resource limit for current plan exceeded
- localizable_data_should_be_object - localizable fields must be objects
Name
403 Forbidden
Description
Plan limit exceeded.
- plan_limit_exceeded - resource limit exceeded

Request

PUT

/v1/:env/collections/:collection/resources/?external_id=<value>

curl -X PUT "https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/?external_id=blog-post-42" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "data": {
        "title": {
            "en": "Welcome to Our Blog"
        },
        "content": {
            "en": "This is our first blog post..."
        },
        "published": true,
        "author": "john_doe"
    },
    "name": "Welcome Post"
}'

Response (201 Created)

{
    "key": "8m3n7k2p",
    "name": "Welcome Post",
    "folder": "6b4qd369",
    "content_type": "document",
    "external_id": "blog-post-42",
    "created_at": "2025-06-16T15:30:01.514282-05:00",
    "resource_owner": null,
    "current_revision": "9q5r8t1w",
    "vectors_size": 0
}

Response (200 Updated)

{
    "key": "8m3n7k2p",
    "name": "Welcome Post",
    "folder": "6b4qd369",
    "content_type": "document",
    "external_id": "blog-post-42",
    "created_at": "2025-06-16T15:30:01.514282-05:00",
    "resource_owner": null,
    "current_revision": "5f2g8h3j",
    "vectors_size": 0
}

GETapi.foxnose.net/v1/:env/collections/:collection/resources/:resource/

Retrieve Resource

Retrieves details of a specific resource.

Success Response: 200 OK

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to view this resource.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- environment_not_found - the specified environment does not exist
- collection_not_found - the specified collection does not exist
- resource_not_found - the specified resource does not exist

Request

GET

/v1/:env/collections/:collection/resources/:resource/

curl https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/8m3n7k2p/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

Response

{
    "key": "8m3n7k2p",
    "name": "Welcome Post",
    "folder": "6b4qd369",
    "content_type": "document",
    "external_id": null,
    "created_at": "2025-06-15T10:30:00.000000-05:00",
    "resource_owner": null,
    "current_revision": "9q5r8t1w",
    "vectors_size": 0
}

PUTapi.foxnose.net/v1/:env/collections/:collection/resources/:resource/

Update Resource

Updates mutable metadata for a resource. Use the Revisions API to change the actual content payload.

Success Response: 200 OK

Request Body

Name
name
Type
string
Default
default:null
Description
Human-readable resource name (1-255 characters). Send null to remove the name, or omit to leave it unchanged.

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to modify this resource.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- environment_not_found
- collection_not_found
- resource_not_found
Name
422 Unprocessable Content
Description
Validation error (for example, empty name).
- validation_error - invalid request data

Request

PUT

/v1/:env/collections/:collection/resources/:resource/

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/8m3n7k2p/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{ "name": "Welcome Post (Updated)" }'

Response

{
    "key": "8m3n7k2p",
    "name": "Welcome Post (Updated)",
    "folder": "6b4qd369",
    "content_type": "document",
    "external_id": null,
    "created_at": "2025-06-15T10:30:00.000000-05:00",
    "resource_owner": null,
    "current_revision": "9q5r8t1w",
    "vectors_size": 0
}

GETapi.foxnose.net/v1/:env/collections/:collection/resources/:resource/data/

Resource Data

Retrieves the JSON payload of the resource's current revision. Use this endpoint when you need the latest published (non-draft) content, and the Revisions API to inspect historical revisions.

Success Responses:

200 OK – data returned successfully
202 Accepted – data is still being processed (retry later)
204 No Content – the resource does not have a published revision yet

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to view this resource's data.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- environment_not_found
- collection_not_found
- resource_not_found

Request

GET

/v1/:env/collections/:collection/resources/:resource/data/

curl https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/8m3n7k2p/data/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

Response (200)

{
    "title": {
        "en": "Welcome to Our Blog",
        "es": "Bienvenidos a Nuestro Blog"
    },
    "content": {
        "en": "This is our first blog post...",
        "es": "Esta es nuestra primera entrada..."
    },
    "published": true,
    "author": "john_doe"
}

DELETEapi.foxnose.net/v1/:env/collections/:collection/resources/:resource/

Delete Resource

Permanently deletes a resource along with all revisions and stored vectors.

This operation cannot be undone. All revision history will be permanently lost.

Success Response: 204 No Content

Errors

Name
401 Unauthorized
Description
Authentication credentials are missing or invalid.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Insufficient permissions to delete this resource.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
The specified resource could not be found. Specific codes:
- environment_not_found - the specified environment does not exist
- collection_not_found - the specified collection does not exist
- resource_not_found - the specified resource does not exist

Request

DELETE

/v1/:env/collections/:collection/resources/:resource/

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/8m3n7k2p/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"