🧩API

Introduction

Authorization

The Conserver API provides a token based authentication, controlled by the environment variable CONSERVER_API_TOKEN in the environment. When not defined or empty, it is disabled. To enable, define CONSERVER_API_TOKEN in the .env file

vCon Management

Gets a list of vCon UUIDs

get

Enables pagination of vCon UUIDs. Use the page and size parameters to paginate the results. Can also filter by date with the since and until parameters.

Query parameters

pageintegerOptionalDefault: 1

sizeintegerOptionalDefault: 50

sincestring · date-timeOptional

untilstring · date-timeOptional

Responses

200

Successful Response

application/json

Responsestring[]

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /vcon HTTP/1.1
Host: 
Accept: */*

[
  "text"
]

Inserts a vCon into the database

post

How to insert a vCon into the database.

Body

vconstringRequired

uuidstring · uuidRequired

created_atany ofRequired

integerOptional

or

stringOptional

or

string · date-timeOptional

subjectany ofOptional

stringOptional

or

nullOptional

redactedobject · RedactedOptionalDefault: {}

appendedany ofOptional

objectOptional

or

nullOptional

groupobject[]OptionalDefault: []

partiesobject[]OptionalDefault: []

dialogobject[]OptionalDefault: []

analysisobject[]OptionalDefault: []

attachmentsobject[]OptionalDefault: []

metaany ofOptionalDefault: {}

objectOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

HTTPcURLJavaScriptPython

POST /vcon HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 208

{
  "vcon": "text",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": 1,
  "subject": "text",
  "redacted": {},
  "appended": {},
  "group": [
    {}
  ],
  "parties": [
    {}
  ],
  "dialog": [
    {}
  ],
  "analysis": [
    {}
  ],
  "attachments": [
    {}
  ],
  "meta": {}
}

{
  "vcon": "text",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": 1,
  "subject": "text",
  "redacted": {},
  "appended": {},
  "group": [
    {}
  ],
  "parties": [
    {}
  ],
  "dialog": [
    {}
  ],
  "analysis": [
    {}
  ],
  "attachments": [
    {}
  ],
  "meta": {}
}

Gets a particular vCon by UUID

get

How to get a particular vCon by UUID

Path parameters

vcon_uuidstring · uuidRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /vcon/{vcon_uuid} HTTP/1.1
Host: 
Accept: */*

{
  "vcon": "text",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": 1,
  "subject": "text",
  "redacted": {},
  "appended": {},
  "group": [
    {}
  ],
  "parties": [
    {}
  ],
  "dialog": [
    {}
  ],
  "analysis": [
    {}
  ],
  "attachments": [
    {}
  ],
  "meta": {}
}

Deletes a particular vCon by UUID

delete

How to remove a vCon from the conserver.

Path parameters

vcon_uuidstring · uuidRequired

Responses

204

Successful Response

422

Validation Error

application/json

delete

HTTPcURLJavaScriptPython

DELETE /vcon/{vcon_uuid} HTTP/1.1
Host: 
Accept: */*

No content

Search vCons based on various parameters

get

Search for vCons using personal identifiers and metadata.

Query parameters

telany ofOptional

Phone number to search for

stringOptional

or

nullOptional

mailtoany ofOptional

Email address to search for

stringOptional

or

nullOptional

nameany ofOptional

Name of the party to search for

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /vcons/search HTTP/1.1
Host: 
Accept: */*

[
  {
    "uuid": "text",
    "created_at": "2025-06-17T04:46:07.095Z",
    "updated_at": "2025-06-17T04:46:07.095Z",
    "subject": "text",
    "parties": [
      {}
    ]
  }
]

Chain Management

Chains are series of links that process a vCon. Before processing a vCon, be sure to load it.

Inserts a vCon UUID into one or more chains

post

Inserts a vCon UUID into one or more chains.

Query parameters

ingress_liststringRequired

Body

string[]Optional

Responses

204

Successful Response

422

Validation Error

application/json

post

HTTPcURLJavaScriptPython

POST /vcon/ingress?ingress_list=text HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 8

[
  "text"
]

No content

Removes one or more vCon UUIDs from the output of a chain (egress)

get

Removes one or more vCon UUIDs from the output of a chain (egress)

Query parameters

egress_liststringRequired

limitanyOptionalDefault: 1

Responses

204

Successful Response

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /vcon/egress?egress_list=text HTTP/1.1
Host: 
Accept: */*

No content

Returns the number of vCons at the end of a chain

get

Returns the number of vCons at the end of a chain.

Query parameters

egress_liststringRequired

Responses

204

Successful Response

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /vcon/count?egress_list=text HTTP/1.1
Host: 
Accept: */*

No content

Configuration

Returns the config file for the conserver

get

Returns the config file for the conserver

Responses

200

Successful Response

application/json

Responseany

get

HTTPcURLJavaScriptPython

GET /config HTTP/1.1
Host: 
Accept: */*

200

Successful Response

No content

Updates the config file for the conserver

post

Updates the config file for the conserver

Query parameters

update_file_nameanyOptional

Body

object · ConfigOptional

Responses

204

Successful Response

422

Validation Error

application/json

post

HTTPcURLJavaScriptPython

POST /config HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

No content

Clears the config file for the conserver

delete

Clears the config file for the conserver

Responses

204

Successful Response

delete

HTTPcURLJavaScriptPython

DELETE /config HTTP/1.1
Host: 
Accept: */*

204

Successful Response

No content

Dead Letter Queue

Reprocess the dead letter queue

post

Move the dead letter queue vcons back to the ingress chain

Query parameters

ingress_liststringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

post

HTTPcURLJavaScriptPython

POST /dlq/reprocess?ingress_list=text HTTP/1.1
Host: 
Accept: */*

No content

Get Vcons list from the dead letter queue

get

Get Vcons list from the dead letter queue, returns array of vcons.

Query parameters

ingress_liststringRequired

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

GET /dlq?ingress_list=text HTTP/1.1
Host: 
Accept: */*

No content

Lifecyle

Forces a reset of the vcon search list

get

Forces a reset of the vcon search list, returns the number of vCons indexed.

Responses

200

Successful Response

application/json

Responseany

get

HTTPcURLJavaScriptPython

GET /index_vcons HTTP/1.1
Host: 
Accept: */*

200

Successful Response

No content