Resources

Authentication: JWT | API Key

Resources represent individual content items stored within folders. Each resource maintains a complete revision history, enabling version control and content rollback capabilities. Resources can be either collection-based (following folder schemas) or component-based (using reusable component schemas).

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 collection folder models or component schemas
Localization Support - manage multilingual content with locale-specific data
Reference Management - establish relationships between content items

Learn more about related resources:

Folders API - manage folders that contain resources
Components API - manage reusable component schemas
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
:folder
Type
string
Description
Unique identifier of the folder (collection or component-based)
Name
:resource
Type
string
Description
Unique identifier of the resource

Use /v1/:env/folders/:folder_key/resources/ for both collection folders and folders that store component-based resources.

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 folder this resource belongs to.
Name
content_type
Type
string
Description
Always "document" for resources.
Name
component
Type
string
Description
Key of the component schema used (for component-based folders). null for collection folders.
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 folders 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

Collection-Based Resources

Resources in collection folders follow the folder's schema model. The data structure is defined by the folder's current schema version and must include all required fields. Draft mode ("mode": "draft") and validation toggles are only available for collection folders.

Component-Based Resources

Resources using component schemas must specify the component query parameter during creation. The data structure follows the component's current published version.

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 folder (which can be the same folder or another folder).
Relation fields can link to multiple resources in the specified folder.
Values use the format folder_key::resource_key for both references and relations.
Strict-reference folders 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. If the organization runs out of units, the API responds with 429 + insufficient_units during creation.

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/folders/:folder/resources/

List Resources

Retrieves all resources in the specified folder.

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 folders).
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 folder, 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
- folder_not_found - the specified folder does not exist

Request

GET

/v1/:env/folders/:folder/resources/

curl https://api.foxnose.net/v1/7c9h4pwu/folders/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",
            "component": null,
            "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",
            "component": null,
            "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/folders/:folder/resources/

Create Resource

Creates a new resource in the specified folder. The resource structure must conform to the folder's schema (for collection folders) or specified component schema (for other folder types).

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

Query Parameters

Name
component
Type
string
Description
Component key for component-based folders. Required when the folder is not a collection.
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 folder's schema or component 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 folder inherits strict references. Provide the parent resource key from the parent folder.
Name
mode
Type
string
Default
default:"instant"
Description
Creation mode:
- instant – validate data and publish immediately
- draft – create a draft revision (collections only)
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
- folder_not_found - the specified folder does not exist
- component_not_found - the specified component does not exist
Name
409 Conflict
Description
A resource with the specified external_id already exists in this folder.
- external_id_conflict - the provided external_id is already in use; use the PUT upsert endpoint to update existing resources by external_id
Name
429 Too Many Requests
Description
Not enough vectorization units to process the resource.
- insufficient_units - add more units or reduce content size
Name
422 Unprocessable Content
Description
Validation or business logic error. Specific codes:
- validation_error - data validation errors against schema
- component_required - component parameter required for non-collection folders
- component_doesnt_have_active_version - component has no active version
- component_schema_not_published - component version exists but is not published
- resource_owner_required - resource owner required for strict reference folders
- resource_owner_not_found - specified resource owner does not exist
- json_size_exceeded - data size exceeds 1MB limit
- draft_not_supported - draft mode is available only for collection folders
- plan_limit_exceeded - resource limit for current plan exceeded
- localizable_data_should_be_object - localizable fields must be objects

Request

POST

/v1/:env/folders/:folder/resources/

curl https://api.foxnose.net/v1/7c9h4pwu/folders/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",
    "component": null,
    "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/folders/:folder/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 folder, 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 folder. Allowed characters: a-z A-Z 0-9 - _ / ., max 255 characters.
Name
component
Type
string
Description
Component key for component-based folders. Must match the component of an existing resource (otherwise 422).
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 folder's schema or component 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 (collection folders only)
Name
resource_owner
Type
string
Description
Parent resource key (strict-reference folders 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
component must match the existing resource's component (otherwise 422)

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
- component_mismatch - component in the request does not match the existing resource's component (only on update; on creation the component is set for the first time)
- component_required - component parameter required for non-collection folders
- component_doesnt_have_active_version - component has no active version
- component_schema_not_published - component version exists but is not published
- resource_owner_required - resource owner required for strict reference folders
- resource_owner_not_found - specified resource owner does not exist
- json_size_exceeded - data size exceeds 1MB limit
- draft_not_supported - draft mode is available only for collection folders
- plan_limit_exceeded - resource limit for current plan exceeded
- localizable_data_should_be_object - localizable fields must be objects
Name
429 Too Many Requests
Description
Plan limit exceeded.
- plan_limit_exceeded - resource or unit limit exceeded

Request

PUT

/v1/:env/folders/:folder/resources/?external_id=<value>

curl -X PUT "https://api.foxnose.net/v1/7c9h4pwu/folders/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",
    "component": null,
    "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",
    "component": null,
    "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/folders/:folder/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
- folder_not_found - the specified folder does not exist
- resource_not_found - the specified resource does not exist

Request

GET

/v1/:env/folders/:folder/resources/:resource/

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

Response

{
    "key": "8m3n7k2p",
    "name": "Welcome Post",
    "folder": "6b4qd369",
    "content_type": "document",
    "component": null,
    "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/folders/:folder/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
- folder_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/folders/:folder/resources/:resource/

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/folders/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",
    "component": null,
    "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/folders/:folder/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
- folder_not_found
- resource_not_found

Request

GET

/v1/:env/folders/:folder/resources/:resource/data/

curl https://api.foxnose.net/v1/7c9h4pwu/folders/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/folders/:folder/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
- folder_not_found - the specified folder does not exist
- resource_not_found - the specified resource does not exist

Request

DELETE

/v1/:env/folders/:folder/resources/:resource/

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