API Reference
The Fency API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The Fency API doesn't support bulk updates. You can work on only one object per request.
Secret keys
The Fency API uses secret keys to authenticate requests. Secret keys can be obtained in the Fency Dashboard.
Your secret keys carry many privileges, so be sure to keep them secure! Do not share your secret keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via bearer auth. Provide your secret key as -H "Authorization: Bearer sk_123...".
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
curl https://api.fency.ai/v1/memories \
-H "Authorization: Bearer sk_123..."
Pagination
All top-level API resources have support for bulk fetches through "list" API methods. For example, you can list Memories. These list API methods share a common structure and accept the parameters nextPageToken and previousPageToken.
The nextPageToken parameter returns the items listed after the last item in the current list.
The previousPageToken parameter returns the items listed before the first item in the current list.
These parameters are mutually exclusive. You can use either the nextPageToken or previousPageToken parameter, but not both simultaneously.
curl -X GET https://api.fency.ai/v1/memories?nextPageToken=MjAyNC0wNC0wOF \
-H 'Content-Type: application/json' \
-H 'Authorization : Bearer sk_123...'
Webhooks
Webhooks are a way to receive real-time notifications from the API when a specific event occurs. For example, you can receive an event when a memory is created, updated, or deleted.
To start receiving webhook events, create and register a webhook through the dashboard.
Webhook Event Types
See the webhook event types for a list of all available event types.
Webhook Security
A cryptographically secure secret should be generated and persisted on your own server. When you create a webhook in dashboard, the secret must be provided.
We will use the secret to generate a signature on each webhook request, provided in the x-fency-signature header. Seeverifying the payload signature for instructions on using the secret to verify that the request originated from Fency.
Webhook Payload Signature Verification
Requests to your endpoint will bear an x-fency-signature header verifying that the request has come from us.
The signature is the HMAC hex digest of the payload, where the algorithm is sha256, the key is your own secret, and the payload is the raw UTF-8 request body received from us. The signature is then prefixed with sha256=.
A delivery of {"payload":"example"} signed with example-secret would have an x-fency-signature of sha256=c395de9ac90297578092d5d0394dc8def76ab5561ec1717dadb6aece0f40bd04.
const secret = "example-secret";
const payload = req.body; // {"payload":"example"}
// Read signature from request HTTP header
const fencySignature = Buffer.from(req.get("x-fency-signature"), "utf8");
// Compute signature using your secret and the request payload
const hmac = crypto.createHmac("sha256", secret);
const digest = Buffer.from("sha256=" + hmac.update(payload).digest("hex"), "utf8");
// Check whether they match, using timing-safe equality (don't use ==)
if (!crypto.timingSafeEqual(digest, fencySignature)) {
throw new Error("Signature invalid");
}
Memories
The memory object represents stored data that can be created, updated, and retrieved. Memories support custom metadata and content that can be used to persist information for your application.
The Memory Object
The unique identifier of the memory.
The timestamp the object was created.
The timestamp when the memory was last updated.
The source type of the memory (e.g. TEXT, URL, FILE).
The type identifier for the memory.
The title of the memory.
The full content of the memory.
The number of content parts in the memory.
The synchronization status of the content.
Custom key-value metadata for the memory.
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Create a memory
You can create memories by text, URL, or file upload.
Create memory by text
Creates a memory from plain text content.
The type identifier for the memory.
Set to TEXT.
The title of the memory.
The text content of the memory.
Optional custom key-value metadata for the memory.
curl -X POST https://api.fency.ai/v1/memories \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"sourceType": "TEXT",
"title": "My text memory",
"text": "This is the content of my text memory.",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}'
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "My text memory",
"content": null,
"contentParts": null,
"contentStatus": "SYNCHRONIZING",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Create memory by URL
Creates a memory by fetching content from a URL.
The type identifier for the memory.
Set to URL.
The title of the memory.
The URL to fetch content from.
Optional custom key-value metadata for the memory.
curl -X POST https://api.fency.ai/v1/memories \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"sourceType": "URL",
"title": "My URL memory",
"url": "https://example.com/article",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}'
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "FILE",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "My URL memory",
"content": null,
"contentParts": null,
"contentStatus": "SYNCHRONIZING",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Create memory by file
Creates a memory with file source type. To upload file content, first create a memory with this endpoint, then call Create upload for memory with the returned memory ID to obtain a presigned upload URL. For the complete flow with code examples, see the Uploading files for memories guide.
The type identifier for the memory.
Set to FILE.
The title of the memory.
Optional custom key-value metadata for the memory.
curl -X POST https://api.fency.ai/v1/memories \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"sourceType": "FILE",
"title": "My file memory",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}'
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "FILE",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "My file memory",
"content": null,
"contentParts": null,
"contentStatus": "EMPTY",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
List memories
Returns a list of memories. Supports pagination via nextPageToken and previousPageToken query parameters.
Optional. Token for the next page of results.
Optional. Token for the previous page of results.
Optional. Maximum number of items to return.
Optional. Sort order (ascending when true).
Array of memory objects. See The memory object.
Pagination object with previousPageToken and nextPageToken.
curl -X GET https://api.fency.ai/v1/memories \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..."
{
"items": [
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
],
"pagination": {
"previousPageToken": "<remove-me>",
"nextPageToken": "YWNlNGM2NjYtYzRiYi00MDk4LWE2MWItNThlNjNkNTlhM2E3"
}
}
Retrieve a Memory
Retrieves the memory for a unique id.
The unique identifier of the memory.
curl -X GET https://api.fency.ai/v1/memories/:id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..."
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Update a Memory
Updates a memory. Only provided fields will be updated.
The unique identifier of the memory.
Optional. The title of the memory.
Optional. Updated text content (for TEXT source type).
Optional. Updated URL (for URL source type).
Optional. Custom key-value metadata for the memory.
curl -X PATCH https://api.fency.ai/v1/memories/:id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"title": "Updated Memory Title",
"text": "Updated content for the memory.",
"url": "https://example.com/updated-memory.pdf",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}'
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Delete a Memory
Permanently deletes a memory. This action cannot be undone.
The unique identifier of the memory.
curl -X DELETE https://api.fency.ai/v1/memories/:id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..."
Create upload for memory
Creates a presigned upload URL for uploading a file to a memory. First create a memory with sourceType: FILE (see Create memory by file), then call this endpoint with the returned memory ID to get an upload URL. See the Uploading files for memories guide for the full flow with code examples.
The unique identifier of the memory.
The name of the file to upload.
The size of the file in bytes.
The MIME type of the file (e.g. application/pdf).
Presigned S3 upload request containing amzDate, amzSignature, amzAlgorithm, amzCredential, policy, key, uploadUrl, and sessionToken. Use these fields to construct a multipart form and POST to uploadUrl.
curl -X POST https://api.fency.ai/v1/memories/:id/uploads \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"fileName": "document.pdf",
"fileSize": 1024,
"mimeType": "application/pdf"
}'
{
"awsS3PostRequest": {
"amzDate": "20231001T000000Z",
"amzSignature": "example-signature",
"amzAlgorithm": "AWS4-HMAC",
"amzCredential": "example-credential",
"policy": "example-policy",
"key": "example-key",
"uploadUrl": "https://example-bucket.s3.amazonaws.com",
"sessionToken": "example-session-token"
}
}
Memory Types
Memory types define the schema for memories, including custom metadata fields and relations. Use memory types to organize and structure the data stored in your memories.
The Memory Type Object
The unique identifier of the memory type.
The timestamp the object was created.
The name of the memory type.
A description of the memory type.
An array of metadata field definitions. Each field has name, description, and fieldType.
{
"id": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"name": "example_memory_type",
"description": "This is an example memory type description.",
"metadataFields": [
{
"name": "department",
"description": "Owning department for this memory.",
"fieldType": "STRING"
}
]
}
Create a memory type
Creates a new memory type with the given name and description.
The name of the memory type.
A description of the memory type.
curl -X POST https://api.fency.ai/v1/memory-types \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"name": "Example Memory Type",
"description": "This is an example memory type description."
}'
{
"id": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"name": "example_memory_type",
"description": "This is an example memory type description.",
"metadataFields": [
{
"name": "department",
"description": "Owning department for this memory.",
"fieldType": "STRING"
}
]
}
List memory types
Returns a list of memory types. Supports pagination via nextPageToken and previousPageToken query parameters.
Optional. Token for the next page of results.
Optional. Token for the previous page of results.
Optional. Maximum number of items to return.
Optional. Sort order (ascending when true).
Array of memory type objects. See The memory type object.
Pagination object with previousPageToken and nextPageToken.
curl -X GET https://api.fency.ai/v1/memory-types \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..."
{
"items": [
{
"id": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"name": "example_memory_type",
"description": "This is an example memory type description.",
"metadataFields": [
{
"name": "department",
"description": "Owning department for this memory.",
"fieldType": "STRING"
}
]
}
],
"pagination": {
"previousPageToken": null,
"nextPageToken": "YWNlNGM2NjYtYzRiYi00MDk4LWE2MWItNThlNjNkNTlhM2E3"
}
}
Retrieve a Memory Type
Retrieves the memory type for a unique id.
The unique identifier of the memory type.
curl -X GET https://api.fency.ai/v1/memory-types/:id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..."
{
"id": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"name": "example_memory_type",
"description": "This is an example memory type description.",
"metadataFields": [
{
"name": "department",
"description": "Owning department for this memory.",
"fieldType": "STRING"
}
]
}
Delete a Memory Type
Permanently deletes a memory type. This action cannot be undone.
The unique identifier of the memory type.
curl -X DELETE https://api.fency.ai/v1/memory-types/:id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..."
Sessions
Sessions contain short-lived tokens used to authenticate client-side operations such as streaming, chat completions, and agent tasks. Create a session on your server using your secret key, then pass the returned clientToken to your client.
The Session Object
The unique identifier for the session.
The timestamp the object was created.
The session type: CREATE_STREAM, CREATE_AGENT_TASK, or CREATE_AGENT_TASK_FILE_DOWNLOAD.
A short-lived token used to authenticate client-side operations. Pass this to your client; it should never be stored or logged.
{
"id": "ses_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"type": "CREATE_AGENT_TASK",
"clientToken": "cf4fe6caa10b4009a8b103d2d5d64042"
}
Create a session
Create a session by sending a POST request to /v1/sessions with one of: createStream for real-time streams, or createAgentTask for streaming, structured, or memory chat completions.
Create stream session
Creates a session for real-time streaming. Use the returned clientToken with FencyProvider via the fetchCreateStreamClientToken callback.
curl -X POST https://api.fency.ai/v1/sessions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"createStream": {}
}'
{
"id": "ses_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"type": "CREATE_STREAM",
"clientToken": "cf4fe6caa10b4009a8b103d2d5d64042"
}
Create agent task session
Creates a session for agent tasks: streaming, structured, memory chat, or memory search completions. Use the returned clientToken via the fetchCreateAgentTaskClientToken callback.
Streaming chat completion agent task
Creates a session for an agent task session of type streaming chat completion. Use the returned clientToken via the fetchCreateAgentTaskClientToken callback.
Set to STREAMING_CHAT_COMPLETION.
curl -X POST https://api.fency.ai/v1/sessions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"createAgentTask": {
"taskType": "STREAMING_CHAT_COMPLETION"
}
}'
{
"id": "ses_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"type": "CREATE_AGENT_TASK",
"clientToken": "cf4fe6caa10b4009a8b103d2d5d64042"
}
Structured chat completion agent task
Creates a session for an agent task session of type structured chat completion. Use the returned clientToken via the fetchCreateAgentTaskClientToken callback.
Set to STRUCTURED_CHAT_COMPLETION.
curl -X POST https://api.fency.ai/v1/sessions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"createAgentTask": {
"taskType": "STRUCTURED_CHAT_COMPLETION"
}
}'
{
"id": "ses_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"type": "CREATE_AGENT_TASK",
"clientToken": "cf4fe6caa10b4009a8b103d2d5d64042"
}
Memory chat agent task
Creates a session for an agent task session of type memory chat completion. Use guardRails.memoryTypes to restrict which memories the task can access. Use the returned clientToken via the fetchCreateAgentTaskClientToken callback.
Set to MEMORY_CHAT.
Array of memory type configs specifying which memories the task can access. Each item can include memoryTypeId, memoryIds, and match for metadata filtering.
curl -X POST https://api.fency.ai/v1/sessions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"createAgentTask": {
"taskType": "MEMORY_CHAT",
"guardRails": {
"memoryTypes": [
{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryIds": [
"mem_cf4fe6caa10b4009a8b103d2d5d64042"
]
}
]
}
}
}'
{
"id": "ses_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"type": "CREATE_AGENT_TASK",
"clientToken": "cf4fe6caa10b4009a8b103d2d5d64042"
}
Memory search agent task
Creates a session for an agent task session of type memory search. Use guardRails.memoryTypes to restrict which memories the task can search. Use the returned clientToken via the fetchCreateAgentTaskClientToken callback.
Set to MEMORY_SEARCH.
Array of memory type configs specifying which memories the task can search. Each item can include memoryTypeId, memoryIds, and match for metadata filtering.
curl -X POST https://api.fency.ai/v1/sessions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..." \
--json '{
"createAgentTask": {
"taskType": "MEMORY_SEARCH",
"guardRails": {
"memoryTypes": [
{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryIds": [
"mem_cf4fe6caa10b4009a8b103d2d5d64042"
]
}
]
}
}
}'
{
"id": "ses_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"type": "CREATE_AGENT_TASK",
"clientToken": "cf4fe6caa10b4009a8b103d2d5d64042"
}
Agent Tasks
Agent tasks represent asynchronous work such as memory chat, memory search, or chat completions. Create a session with an agent task, then poll or subscribe to webhooks to track task status and results.
The Agent Task Object
The unique identifier of the agent task.
The timestamp the object was created.
The timestamp when the agent task was last updated.
Task status: IN_PROGRESS, SUCCEEDED, or FAILED.
Kind of task (e.g. MEMORY_CHAT, MEMORY_SEARCH, STREAMING_CHAT_COMPLETION, STRUCTURED_CHAT_COMPLETION).
When the task completed successfully, if applicable.
Task-specific success payload when status is SUCCEEDED. The shape depends on taskType; see the sections below for each variant.
When the task failed, if applicable.
Error details when status is FAILED.
Custom key-value metadata for the agent task.
Full JSON examples for each taskType are in the subsections below: Memory chat, Memory search, Streaming chat completion, and Structured chat completion.
Memory chat (MEMORY_CHAT)
For taskType MEMORY_CHAT, when the task has SUCCEEDED, successResponse includes the assistant reply and cited sources. Common task fields (id, status, timestamps, etc.) are described in The Agent Task Object.
The assistant message generated from your memories.
When the reply was finalized.
Citations: memory type, memory id, title, and optional page numbers for each source used.
{
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"status": "SUCCEEDED",
"taskType": "MEMORY_CHAT",
"succeededAt": "2024-04-08T17:02:27.887295Z",
"successResponse": {
"text": "Example assistant reply based on your memories.",
"completedAt": "2024-04-08T17:02:27.887295Z",
"sources": [
{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTypeName": "Example Memory Type",
"memoryId": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTitle": "Example memory title",
"pageNumbers": [
1,
2
]
}
]
},
"failedAt": null,
"failureResponse": null,
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Memory search (MEMORY_SEARCH)
For taskType MEMORY_SEARCH, successResponse contains the search query and ranked memory hits. See The Agent Task Object for shared fields.
The search query used for this task.
When the search completed.
Each item includes memory metadata, a matchingChunk (chunk number, page numbers, content), matchingChunkScore, and optional chunks with surrounding context and a relation (e.g. MATCH, CONTEXT_BEFORE).
{
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64043",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"status": "SUCCEEDED",
"taskType": "MEMORY_SEARCH",
"succeededAt": "2024-04-08T17:02:27.887295Z",
"successResponse": {
"completedAt": "2024-04-08T17:02:27.887295Z",
"query": "What did we decide about pricing?",
"items": [
{
"memoryId": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTitle": "Pricing notes",
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTypeName": "Docs",
"matchingChunk": {
"chunkNumber": 3,
"pageNumbers": [
1
],
"content": "We agreed on tiered pricing for enterprise customers."
},
"matchingChunkScore": 0.92,
"chunks": [
{
"chunkNumber": 2,
"pageNumbers": [
1
],
"content": "Previous section context.",
"relation": "CONTEXT_BEFORE"
},
{
"chunkNumber": 3,
"pageNumbers": [
1
],
"content": "We agreed on tiered pricing for enterprise customers.",
"relation": "MATCH"
}
]
}
]
},
"failedAt": null,
"failureResponse": null,
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Streaming chat completion (STREAMING_CHAT_COMPLETION)
For STREAMING_CHAT_COMPLETION, the finalized successResponse includes the full assistant text and the message history. Shared task fields are documented in The Agent Task Object.
The complete assistant reply after streaming finishes.
Conversation turns with role and content (e.g. USER, ASSISTANT).
When the completion finished.
{
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64044",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"status": "SUCCEEDED",
"taskType": "STREAMING_CHAT_COMPLETION",
"succeededAt": "2024-04-08T17:02:27.887295Z",
"successResponse": {
"text": "The answer is 42.",
"completedAt": "2024-04-08T17:02:27.887295Z",
"messages": [
{
"role": "USER",
"content": "What is the answer?"
},
{
"role": "ASSISTANT",
"content": "The answer is 42."
}
]
},
"failedAt": null,
"failureResponse": null,
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Structured chat completion (STRUCTURED_CHAT_COMPLETION)
For STRUCTURED_CHAT_COMPLETION, successResponse includes JSON parsed from the model output plus the message history. See The Agent Task Object for common attributes.
The structured payload returned by the model (shape depends on your schema).
Conversation turns with role and content; the assistant message may contain the raw model string before parsing.
When the structured completion finished.
{
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64045",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"status": "SUCCEEDED",
"taskType": "STRUCTURED_CHAT_COMPLETION",
"succeededAt": "2024-04-08T17:02:27.887295Z",
"successResponse": {
"json": {
"answer": "yes",
"confidence": 0.95
},
"completedAt": "2024-04-08T17:02:27.887295Z",
"messages": [
{
"role": "USER",
"content": "Is this request valid JSON?"
},
{
"role": "ASSISTANT",
"content": "{\"answer\":\"yes\",\"confidence\":0.95}"
}
]
},
"failedAt": null,
"failureResponse": null,
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
List agent tasks
Returns a list of agent tasks. Supports pagination via nextPageToken and previousPageToken query parameters.
Optional. Token for the next page of results.
Optional. Token for the previous page of results.
Optional. Maximum number of items to return.
Optional. Sort order (ascending when true).
Array of agent task objects. See The agent task object.
Pagination object with previousPageToken and nextPageToken.
curl -X GET https://api.fency.ai/v1/agent-tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..."
{
"items": [
{
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"status": "SUCCEEDED",
"taskType": "MEMORY_CHAT",
"succeededAt": "2024-04-08T17:02:27.887295Z",
"successResponse": {
"text": "Example assistant reply based on your memories.",
"completedAt": "2024-04-08T17:02:27.887295Z",
"sources": [
{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTypeName": "Example Memory Type",
"memoryId": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTitle": "Example memory title",
"pageNumbers": [
1,
2
]
}
]
},
"failedAt": null,
"failureResponse": null,
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
},
{
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64043",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"status": "SUCCEEDED",
"taskType": "MEMORY_SEARCH",
"succeededAt": "2024-04-08T17:02:27.887295Z",
"successResponse": {
"completedAt": "2024-04-08T17:02:27.887295Z",
"query": "What did we decide about pricing?",
"items": [
{
"memoryId": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTitle": "Pricing notes",
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTypeName": "Docs",
"matchingChunk": {
"chunkNumber": 3,
"pageNumbers": [
1
],
"content": "We agreed on tiered pricing for enterprise customers."
},
"matchingChunkScore": 0.92,
"chunks": [
{
"chunkNumber": 2,
"pageNumbers": [
1
],
"content": "Previous section context.",
"relation": "CONTEXT_BEFORE"
},
{
"chunkNumber": 3,
"pageNumbers": [
1
],
"content": "We agreed on tiered pricing for enterprise customers.",
"relation": "MATCH"
}
]
}
]
},
"failedAt": null,
"failureResponse": null,
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
},
{
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64044",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"status": "SUCCEEDED",
"taskType": "STREAMING_CHAT_COMPLETION",
"succeededAt": "2024-04-08T17:02:27.887295Z",
"successResponse": {
"text": "The answer is 42.",
"completedAt": "2024-04-08T17:02:27.887295Z",
"messages": [
{
"role": "USER",
"content": "What is the answer?"
},
{
"role": "ASSISTANT",
"content": "The answer is 42."
}
]
},
"failedAt": null,
"failureResponse": null,
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
},
{
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64045",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"status": "SUCCEEDED",
"taskType": "STRUCTURED_CHAT_COMPLETION",
"succeededAt": "2024-04-08T17:02:27.887295Z",
"successResponse": {
"json": {
"answer": "yes",
"confidence": 0.95
},
"completedAt": "2024-04-08T17:02:27.887295Z",
"messages": [
{
"role": "USER",
"content": "Is this request valid JSON?"
},
{
"role": "ASSISTANT",
"content": "{\"answer\":\"yes\",\"confidence\":0.95}"
}
]
},
"failedAt": null,
"failureResponse": null,
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
],
"pagination": {
"previousPageToken": null,
"nextPageToken": "YWNlNGM2NjYtYzRiYi00MDk4LWE2MWItNThlNjNkNTlhM2E3"
}
}
Retrieve an agent task
Retrieves the agent task for a unique agentTaskId. The example below is a MEMORY_CHAT task; other taskType values use the successResponse shapes documented under The Agent Task Object.
The unique identifier of the agent task.
curl -X GET https://api.fency.ai/v1/agent-tasks/:id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_123..."
{
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"status": "SUCCEEDED",
"taskType": "MEMORY_CHAT",
"succeededAt": "2024-04-08T17:02:27.887295Z",
"successResponse": {
"text": "Example assistant reply based on your memories.",
"completedAt": "2024-04-08T17:02:27.887295Z",
"sources": [
{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTypeName": "Example Memory Type",
"memoryId": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"memoryTitle": "Example memory title",
"pageNumbers": [
1,
2
]
}
]
},
"failedAt": null,
"failureResponse": null,
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Events
Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new event object. For example, when a memory is created, we create an event of type memory.created, and when a memory is updated, we create an event of type memory.updated.
Events contain different data fields depending on its type. For example, a memory.updated event contains the given entity object (the memory object) that was updated.
We have a separate webhooks system for sending the Event objects directly to an endpoint on your server. You can manage webhooks in your account dashboard.
We only guarantee access to the events through the API and dashboard for 30 days.
memory.created
Event published when a new memory is created.
The unique identifier of the event.
The version of the event.
The type of the event.
The timestamp the event was created.
The unique identifier of the organization that the event belongs to.
The memory that was created. See the memory object for the schema.
{
"id": "evt_123e4567e89b12d3a456426614174000",
"type": "memory.created",
"createdAt": "2023-10-01T12:00:00Z",
"entity": {
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
}
memory.updated
Event published when a memory is updated.
The unique identifier of the event.
The version of the event.
The type of the event.
The timestamp the event was created.
The unique identifier of the organization that the event belongs to.
The memory that was updated. See the memory object for the schema.
{
"id": "evt_123e4567e89b12d3a456426614174000",
"type": "memory.updated",
"createdAt": "2023-10-01T12:00:00Z",
"entity": {
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
}
memory.deleted
Event published when a memory is deleted.
The unique identifier of the event.
The version of the event.
The type of the event.
The timestamp the event was created.
The unique identifier of the organization that the event belongs to.
The memory that was deleted. See the memory object for the schema.
{
"id": "evt_123e4567e89b12d3a456426614174000",
"type": "memory.deleted",
"createdAt": "2023-10-01T12:00:00Z",
"entity": {
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
}
agent.task.created
Event published when a new agent task is created (or first observed for delivery).
The unique identifier of the event.
The version of the event.
The type of the event.
The timestamp the event was created.
The unique identifier of the organization that the event belongs to.
The agent task that was created. See the agent task object for the schema.
{
"id": "evt_123e4567e89b12d3a456426614174000",
"type": "agent.task.created",
"createdAt": "2023-10-01T12:00:00Z",
"entity": {
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2023-10-01T12:00:00Z",
"updatedAt": "2023-10-01T12:00:00Z",
"status": "SUCCEEDED",
"taskType": "MEMORY_CHAT",
"succeededAt": "2023-10-01T12:00:00Z",
"successResponse": {},
"failedAt": "2023-10-01T12:00:00Z",
"failureResponse": {
"message": "Task failed: upstream timeout"
},
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
}
agent.task.updated
Event published when an agent task is updated (for example status or result changes).
The unique identifier of the event.
The version of the event.
The type of the event.
The timestamp the event was created.
The unique identifier of the organization that the event belongs to.
The agent task that was updated. See the agent task object for the schema.
{
"id": "evt_123e4567e89b12d3a456426614174000",
"type": "agent.task.updated",
"createdAt": "2023-10-01T12:00:00Z",
"entity": {
"id": "ata_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2023-10-01T12:00:00Z",
"updatedAt": "2023-10-01T12:00:00Z",
"status": "SUCCEEDED",
"taskType": "MEMORY_CHAT",
"succeededAt": "2023-10-01T12:00:00Z",
"successResponse": {},
"failedAt": "2023-10-01T12:00:00Z",
"failureResponse": {
"message": "Task failed: upstream timeout"
},
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
}