Revisions

Authentication: JWT | API Key

Revisions are immutable snapshots of resource content. Every change results in a new revision with an auto-incremented number, allowing teams to restore older states, audit edits, and enforce schema validation before publication.

Revisions enable:

Version Tracking – capture every change with sequential numbers
Content History – inspect past states for auditing or recovery
Draft & Publish Workflow – review data in draft form before publishing (collections only)
Schema Validation – ensure content matches the schema version that was active at creation time
Data Snapshots – retrieve exact JSON payloads that were stored for each revision

Learn more about related resources:

Resources API – manage content resources that contain revisions
Collections API – manage collections that contain resources
Versions API – manage schema versions used for validation
Fields API – define content structure and validation rules

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
Name
:revision
Type
string
Description
Unique identifier of the revision

All endpoints described here use /v1/:env/collections/:collection/resources/:resource/revisions/ as the base path.

Revision Object

Name
key
Type
string
Description
Unique identifier for the revision.
Name
resource
Type
string
Description
Key of the resource this revision belongs to.
Name
schema_version
Type
string
Description
Key of the schema version used for validation.
Name
number
Type
integer
Description
Auto-incremented revision number. Starts at 1 for the first revision.
Name
size
Type
integer
Description
Size of the revision payload in bytes (max 1 MB).
Name
status
Type
string
Description
Publication status. One of draft, published, or unpublished.
Name
is_valid
Type
boolean | null
Description
Draft validation flag. true when the draft passed schema validation, false when validation was skipped or failed, null for published/unpublished revisions.
Name
published_at
Type
datetime | null
Description
Timestamp when the revision became published.
Name
unpublished_at
Type
datetime | null
Description
Timestamp when the revision left the published state.
Name
created_at
Type
datetime
Description
Timestamp when the revision was created, in ISO 8601 format.

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

List Revisions

Retrieves all revisions for the specified resource. Results are ordered by creation date (oldest first) unless ordering=-created_at is supplied.

Success Response: 200 OK

Query Parameters

Name
limit
Type
integer
Default
default:100
Description
Number of items per page (standard limit/offset pagination).
Name
offset
Type
integer
Default
default:0
Description
Number of items to skip before starting the page.
Name
ordering
Type
string
Description
Order by a specific field. Common values:
- created_at – oldest first (default)
- -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 revisions.
- 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/revisions/

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

Response

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "9q5r8t1w",
            "resource": "8m3n7k2p",
            "schema_version": "vr8x2k9m",
            "number": 3,
            "size": 2048,
            "status": "published",
            "is_valid": null,
            "published_at": "2025-06-16T09:15:00.000000-05:00",
            "unpublished_at": null,
            "created_at": "2025-06-16T09:15:00.000000-05:00"
        },
        {
            "key": "2x7z5v8c",
            "resource": "8m3n7k2p",
            "schema_version": "vr8x2k9m",
            "number": 2,
            "size": 1856,
            "status": "unpublished",
            "is_valid": null,
            "published_at": "2025-06-15T14:30:00.000000-05:00",
            "unpublished_at": "2025-06-16T09:15:00.000000-05:00",
            "created_at": "2025-06-15T14:30:00.000000-05:00"
        },
        {
            "key": "1a4b7e9f",
            "resource": "8m3n7k2p",
            "schema_version": "vr8x2k9m",
            "number": 1,
            "size": 1792,
            "status": "published",
            "is_valid": null,
            "published_at": "2025-06-15T10:30:00.000000-05:00",
            "unpublished_at": "2025-06-15T14:30:00.000000-05:00",
            "created_at": "2025-06-15T10:30:00.000000-05:00"
        }
    ]
}

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

Create Revision

Creates a new revision for the specified resource. Collections support both draft and published modes. The API returns 201 Created when wait=true (default) or 202 Accepted when wait=false for asynchronous processing.

Success Response: 201 Created (synchronous) or 202 Accepted (async)

Headers

Name
If-Match
Type
string
Description
Optional conditional-write precondition: the key of the revision you expect to still be current. The write is applied only if it is, and is refused with 412 otherwise. Quotes are accepted and stripped ("abc" and abc are the same value); weak validators (W/"...") and * are not supported. See Conditional writes.

Query Parameters

Name
wait
Type
bool
Default
default:true
Description
When false, the API queues background processing and returns immediately with 202 Accepted. Use the revision data endpoint later to check when the payload becomes available.

Request Body

Name
data
Type
object
Required
required
Description
Required content payload that follows the resource schema.
Name
mode
Type
string
Default
default:"published"
Description
Set to draft to keep the revision in draft status. Omit or use published for immediate publication.
Name
validate_data
Type
boolean
Default
default:true
Description
Applies to draft revisions. When false, the API stores the draft without running schema validation and sets is_valid to false.

Errors

Name
409 Conflict
Description
Two writers collided on this resource's next revision number; nothing was lost.
- revision_number_conflict - retry the same write
Name
412 Precondition Failed
Description
The If-Match precondition no longer holds.
- revision_precondition_failed - detail.current_revision names the revision that is current now; re-read and recompute before retrying
Name
422 Unprocessable Content
Description
The If-Match header itself is malformed — a weak validator, *, or a value that is not a revision key.
- invalid_revision_precondition - fix the header
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 update 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
Name
422 Unprocessable Content
Description
Validation or business rule error. Specific codes:
- validation_error - request body failed validation
- data_size_exceeded - payload exceeds the 1 MB limit
- localizable_data_should_be_object - localized fields must pass locale objects
- collection_doesnt_have_active_version / collection_schema_not_published - collection schema not ready

Request

POST

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

curl https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/8m3n7k2p/revisions/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "data": {
        "title": {
            "en": "Welcome to Our Updated Blog",
            "es": "Bienvenidos a Nuestro Blog Actualizado"
        },
        "content": {
            "en": "This is our updated blog post with new content...",
            "es": "Esta es nuestra entrada actualizada con nuevo contenido..."
        },
        "published": true,
        "author": "john_doe",
        "tags": ["welcome", "blog", "update"]
    },
    "mode": "draft",
    "validate_data": true
}'

Response

{
    "key": "3c8f2h5k",
    "resource": "8m3n7k2p",
    "schema_version": "vr8x2k9m",
    "number": 4,
    "size": 2304,
    "status": "draft",
    "is_valid": true,
    "published_at": null,
    "unpublished_at": null,
    "created_at": "2025-06-16T16:45:00.000000-05:00"
}

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

Retrieve Revision

Retrieves metadata for a specific revision.

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 revision.
- 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
- revision_not_found - the specified revision does not exist

Request

GET

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

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

Response

{
    "key": "9q5r8t1w",
    "resource": "8m3n7k2p",
    "schema_version": "vr8x2k9m",
    "number": 3,
    "size": 2048,
    "status": "published",
    "is_valid": null,
    "published_at": "2025-06-16T09:15:00.000000-05:00",
    "unpublished_at": null,
    "created_at": "2025-06-16T09:15:00.000000-05:00"
}

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

Update Draft Revision

Updates the payload of an existing draft revision. Published and unpublished revisions are read-only.

Success Response: 200 OK

Request Body

Name
data
Type
object
Required
required
Description
Replacement content for the draft revision.
Name
validate_data
Type
boolean
Default
default:true
Description
Runs schema validation against the current schema version when true. Set to false to store the draft without validation (the API sets is_valid=false).

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 edit this revision.
- 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
- revision_not_found - the specified revision does not exist
Name
422 Unprocessable Content
Description
Validation or business rule error. Specific codes:
- revision_not_draft - only draft revisions can be updated
- validation_error - request body failed validation
- data_size_exceeded - payload exceeds the 1 MB limit

Request

PUT

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

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/8m3n7k2p/revisions/3c8f2h5k/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "data": {
        "title": {
            "en": "Welcome to Our Updated Blog (Draft)"
        },
        "content": {
            "en": "Draft copy under review"
        },
        "published": false
    },
    "validate_data": true
}'

Response

{
    "key": "3c8f2h5k",
    "resource": "8m3n7k2p",
    "schema_version": "vr8x2k9m",
    "number": 4,
    "size": 1536,
    "status": "draft",
    "is_valid": true,
    "published_at": null,
    "unpublished_at": null,
    "created_at": "2025-06-16T16:45:00.000000-05:00"
}

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

Delete Revision

Permanently deletes a specific revision. Published revisions (the ones currently live) cannot be deleted.

To remove a published revision, create and publish a new revision first so the previous one becomes unpublished.

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 revision.
- 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
- revision_not_found - the specified revision does not exist
Name
422 Unprocessable Content
Description
Business logic error. Specific codes:
- cannot_delete_current_revision - cannot delete a published revision

Request

DELETE

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

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

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

Retrieve Revision Data

Returns the stored JSON payload for a specific revision. Use this endpoint to review draft content or snapshot data. When the payload is still being prepared, the API responds with 202 Accepted.

Success Response: 200 OK (or 202 Accepted when processing)

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 revision.
- 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
- revision_not_found - the specified revision does not exist

Request

GET

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

curl https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/8m3n7k2p/revisions/9q5r8t1w/data/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "title": {
        "en": "Welcome to Our Updated Blog"
    },
    "content": {
        "en": "This is our updated blog post with new content..."
    },
    "published": true,
    "author": "john_doe",
    "tags": ["welcome", "blog", "update"]
}

POSTapi.foxnose.net/v1/:env/collections/:collection/resources/:resource/revisions/:revision/publish/

Publish Draft Revision

Publishes a draft revision. The API automatically unpublishes the previous live revision so only one revision remains published at a time.

Success Response: 200 OK

Request Body

Name
validate_before_publish
Type
boolean
Default
default:true
Description
When true, requires the draft to have is_valid=true. Set to false to publish without re-validation (not recommended).

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 publish revisions.
- 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
- revision_not_found - the specified revision does not exist
Name
422 Unprocessable Content
Description
Business rule error. Specific codes:
- invalid_status_transition - only drafts can be published
- revision_validation_required - the draft has not passed validation while validate_before_publish=true

Request

POST

/v1/:env/collections/:collection/resources/:resource/revisions/:revision/publish/

curl -X POST https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/8m3n7k2p/revisions/3c8f2h5k/publish/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{"validate_before_publish": true}'

Response

{
    "key": "3c8f2h5k",
    "resource": "8m3n7k2p",
    "schema_version": "vr8x2k9m",
    "number": 4,
    "size": 1536,
    "status": "published",
    "is_valid": null,
    "published_at": "2025-06-17T08:02:00.000000-05:00",
    "unpublished_at": null,
    "created_at": "2025-06-16T16:45:00.000000-05:00"
}

POSTapi.foxnose.net/v1/:env/collections/:collection/resources/:resource/revisions/:revision/validate/

Validate Draft Revision

Runs schema validation for a draft without changing its status. The response contains validation status and error messages (if any). Publishing requires is_valid=true when validate_before_publish is used.

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 validate this revision.
- 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
- revision_not_found - the specified revision does not exist

Request

POST

/v1/:env/collections/:collection/resources/:resource/revisions/:revision/validate/

curl -X POST https://api.foxnose.net/v1/7c9h4pwu/collections/6b4qd369/resources/8m3n7k2p/revisions/3c8f2h5k/validate/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "revision_key": "3c8f2h5k",
    "status": "draft",
    "is_valid": false,
    "errors": [
        "Field \"title.en\" is required"
    ]
}

Revision Lifecycle

Automatic numbering – each resource starts at revision 1 and increments sequentially. Use ordering=-created_at or the number field to locate the latest revision quickly.
Single published revision – publishing a draft automatically unpublishes any previous published revision so only one version stays live.
Draft availability – collections support both draft and published revisions.
Validation state – drafts can skip validation via validate_data=false, but the API marks is_valid=false until you run the validate endpoint successfully.
Data snapshots – metadata endpoints return revision details; use the revision data route when you need the stored JSON payload. Responses may return 202 Accepted while processing completes.
Size limit – each revision payload (and draft update) must not exceed 1 MB. Requests over the limit return 422 data_size_exceeded.