API Reference

Introduction

Jan API is compatible with the OpenAI API.

Models

List and describe the various models available in the API.

The model object Webhook

Describe a model offering that can be used with the API. Equivalent to OpenAI's model object.

Request Body schema: application/json

id	string The identifier of the model.
object	string Default: "model" The type of the object, indicating it's a model.
created	integer <int64> Unix timestamp representing the creation time of the model.
owned_by	string The entity that owns the model.

Request samples

Payload

Content type

application/json

{"id": "trinity-v1.2-7b",
"object": "model",
"created": 1253935178,
"owned_by": "_"
}

List models

Lists the currently available models, and provides basic information about each one such as the owner and availability. Equivalent to OpenAI's list model.

Responses

Request samples

cURL
JavaScript
Node.js
Python

curl -X 'GET' \
  'http://localhost:1337/v1/models' \
  -H 'accept: application/json'

Response samples

200

Content type

application/json

{"object": "list",
"data": [{"source_url": "https://huggingface.co/janhq/trinity-v1.2-GGUF/resolve/main/trinity-v1.2.Q4_K_M.gguf",
"id": "trinity-v1.2-7b",
"object": "model",
"name": "Trinity-v1.2 7B Q4",
"version": "1.0",
"description": "Trinity is an experimental model merge using the Slerp method. Recommended for daily assistance purposes.",
"format": "gguf",
"settings": {"ctx_len": 4096,
"prompt_template": "<|im_start|>system\n{system_message}<|im_end|>\n<|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant"
},
"parameters": {"temperature": 0.7,
"top_p": 0.95,
"stream": true,
"max_tokens": 4096,
"stop": [ ],
"frequency_penalty": 0,
"presence_penalty": 0
},
"metadata": null,
"engine": "nitro"
}
]
}

Download a specific model.

Download a model.

path Parameters

model_id

required

string

Example: mistral-ins-7b-q4

The ID of the model to use for this request.

Responses

Request samples

cURL
JavaScript
Node.js
Python

curl -X 'GET' \  
  'http://localhost:1337/v1/models/download/{model_id}' \  
  -H 'accept: application/json'

Response samples

200

Content type

application/json

{"message": "Starting download mistral-ins-7b-q4"
}

Retrieve model

Get a model instance, providing basic information about the model such as the owner and permissioning. Equivalent to OpenAI's retrieve model.

path Parameters

model_id

required

string

Example: mistral-ins-7b-q4

The ID of the model to use for this request.

Responses

Request samples

cURL
JavaScript
Node.js
Python

curl -X 'GET' \  
  'http://localhost:1337/v1/models/{model_id}' \  
  -H 'accept: application/json'

Response samples

200

Content type

application/json

{"source_url": "https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf",
"id": "mistral-ins-7b-q4",
"object": "model",
"name": "Mistral Instruct 7B Q4",
"version": "1.0",
"description": "Trinity is an experimental model merge using the Slerp method. Recommended for daily assistance purposes.",
"format": "gguf",
"settings": {"ctx_len": 4096,
"prompt_template": "[INST] {prompt} [/INST]"
},
"parameters": {"temperature": 0.7,
"top_p": 0.95,
"stream": true,
"max_tokens": 4096,
"stop": [ ],
"frequency_penalty": 0,
"presence_penalty": 0
},
"metadata": null,
"engine": "nitro"
}

Delete model

Delete a model. Equivalent to OpenAI's delete model.

path Parameters

model_id

required

string

Example: mistral-ins-7b-q4

The model id to delete

Responses

Request samples

cURL
JavaScript
Node.js
Python

curl -X 'DELETE' \
  'http://localhost:1337/v1/models/{model_id}' \
  -H 'accept: application/json'

Response samples

200

Content type

application/json

{"id": "mistral-ins-7b-q4",
"object": "model",
"deleted": true
}

Chat

Given a list of messages comprising a conversation, the model will return a response.

Create chat completion

Creates a model response for the given chat conversation. Equivalent to OpenAI's create chat completion.

Request Body schema: application/json

messages	arrays Contains input data or prompts for the model to process.
model	string Specifies the model being used for inference or processing tasks.
stream	boolean Default: true Enables continuous output generation, allowing for streaming of model responses.
max_tokens	number Default: 2048 The maximum number of tokens the model will generate in a single response.
stop	arrays Defines specific tokens or phrases at which the model will stop generating further output.
frequency_penalty	number Default: 0 Adjusts the likelihood of the model repeating words or phrases in its output.
presence_penalty	number Default: 0 Influences the generation of new and varied concepts in the model's output.
temperature	number Default: 0.7 Controls the randomness of the model's output.
top_p	number Default: 0.95 Set probability threshold for more relevant outputs.

Responses

Request samples

Payload
cURL
JavaScript
Node.js
Python

Content type

application/json

{"messages": [{"content": "You are a helpful assistant.",
"role": "system"
},
{"content": "Hello!",
"role": "user"
}
],
"model": "tinyllama-1.1b",
"stream": true,
"max_tokens": 2048,
"stop": ["hello"
],
"frequency_penalty": 0,
"presence_penalty": 0,
"temperature": 0.7,
"top_p": 0.95
}

Response samples

200

Content type

application/json

{"choices": [{"finish_reason": null,
"index": 0,
"message": {"content": "Hello user. What can I help you with?",
"role": "assistant"
}
}
],
"created": 1700193928,
"id": "ebwd2niJvJB1Q2Whyvkz",
"model": "_",
"object": "chat.completion",
"system_fingerprint": "_",
"usage": {"completion_tokens": 500,
"prompt_tokens": 33,
"total_tokens": 533
}
}

Assistants

Configures and utilizes different AI assistants for varied tasks

The assistant object Webhook

Build assistants that can call models and use tools to perform tasks. Equivalent to OpenAI's assistants object.

Request Body schema: application/json

id	string The identifier of the assistant.
object	string Default: "assistant" Type of the object, indicating it's an assistant.
version	integer Version number of the assistant.
created_at	integer <int64> Unix timestamp representing the creation time of the assistant.
name	string Name of the assistant.
description	string Description of the assistant. Can be null.
avatar	string URL of the assistant's avatar. Jan-specific property.
	Array of objects List of models associated with the assistant. Jan-specific property.
instructions	string A system prompt for the assistant.
	object Event subscription settings for the assistant.
metadata	object Metadata associated with the assistant.

Request samples

Payload

Content type

application/json

{"id": "asst_abc123",
"object": "assistant",
"version": 1,
"created_at": 1698984975,
"name": "Math Tutor",
"description": null,
"avatar": "https://pic.png",
"models": [{"model_id": "model_0"
}
],
"instructions": "Be concise",
"events": {"in": ["string"
],
"out": ["string"
]
},
"metadata": { }
}

List assistants

Return a list of assistants. Equivalent to OpenAI's list assistants.

Responses

Request samples

cURL
JavaScript
Node.js
Python

curl http://localhost:1337/v1/assistants \
  -H "Content-Type: application/json"

Response samples

200

Content type

application/json

[{"id": "asst_abc123",
"object": "assistant",
"version": 1,
"created_at": 1698984975,
"name": "Math Tutor",
"description": null,
"avatar": "https://pic.png",
"models": [{"model_id": "model_0"
}
],
"instructions": "Be concise",
"events": {"in": [ ],
"out": [ ]
},
"metadata": { }
},
{"id": "asst_abc456",
"object": "assistant",
"version": 1,
"created_at": 1698984975,
"name": "Physics Tutor",
"description": null,
"avatar": "https://pic.png",
"models": [{"model_id": "model_1"
}
],
"instructions": "Be concise!",
"events": {"in": [ ],
"out": [ ]
},
"metadata": { }
}
]

Retrieve assistant

Retrieves an assistant. Equivalent to OpenAI's retrieve assistants.

path Parameters

assistant_id

required

string

Example: jan

The ID of the assistant to retrieve.

Responses

Request samples

cURL
JavaScript
Node.js
Python

curl http://localhost:1337/v1/assistants/{assistant_id} \
  -H "Content-Type: application/json"

Response samples

200

Content type

application/json

{"id": "asst_abc123",
"object": "assistant",
"version": 1,
"created_at": 1698984975,
"name": "Math Tutor",
"description": null,
"avatar": "https://pic.png",
"models": [{"model_id": "model_0"
}
],
"instructions": "Be concise",
"events": {"in": ["string"
],
"out": ["string"
]
},
"metadata": { }
}

Messages

Messages capture a conversation's content. This can include the content from LLM responses and other metadata from chat completions.

The message object Webhook

Information about a message in the thread. Equivalent to OpenAI's message object.

Request Body schema: application/json

id	string Sequential or UUID identifier of the message.
object	string Type of the object, defaults to 'thread.message'.
created_at	integer <int64> Unix timestamp representing the creation time of the message.
thread_id	string Identifier of the thread to which this message belongs. Defaults to parent thread.
assistant_id	string Identifier of the assistant involved in the message. Defaults to parent thread.
role	string Enum: "user" "assistant" Role of the sender, either 'user' or 'assistant'.
	Array of objects
metadata	object Metadata associated with the message, defaults to an empty object.

Request samples

Payload

Content type

application/json

{"id": 0,
"object": "thread.message",
"created_at": 0,
"thread_id": "thread_asdf",
"assistant_id": "jan",
"role": "user",
"content": [{"type": "string",
"text": {"value": "Hi!?",
"annotations": [ ]
}
}
],
"metadata": { }
}

List messages

Retrieves all messages from the given thread. Equivalent to OpenAI's list messages.

path Parameters

thread_id

required

string

The ID of the thread from which to retrieve messages.

Responses

Request samples

cURL

curl http://localhost:1337/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json"

Response samples

200

Content type

application/json

{"object": "list",
"data": [{"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699017614,
"thread_id": "thread_abc123",
"role": "user",
"content": [{"type": "string",
"text": {"value": "How does AI work? Explain it in simple terms.",
"annotations": ["string"
]
}
}
],
"file_ids": [ ],
"assistant_id": null,
"run_id": null,
"metadata": { }
}
],
"first_id": "msg_abc123",
"last_id": "msg_abc456",
"has_more": false
}

Create message

Create a message. Equivalent to OpenAI's list messages.

path Parameters

thread_id

required

string

The ID of the thread to which the message will be posted.

Request Body schema: application/json
required

role required	string Enum: "user" "assistant" Role of the sender, either 'user' or 'assistant'.
content required	string Text content of the message.

Responses

Request samples

Payload
cURL

Content type

application/json

{"role": "user",
"content": "How does AI work? Explain it in simple terms."
}

Response samples

200

Content type

application/json

{"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699017614,
"thread_id": "thread_abc123",
"role": "user",
"content": [{"type": "text",
"text": {"value": "How does AI work? Explain it in simple terms.",
"annotations": [ ]
}
}
],
"file_ids": [ ],
"assistant_id": null,
"run_id": null,
"metadata": { }
}

Retrieve message

Retrieve a specific message from a thread using its thread_id and message_id. Equivalent to OpenAI's retrieve messages.

path Parameters

thread_id required	string The ID of the thread containing the message.
message_id required	string The ID of the message to retrieve.

Responses

Request samples

cURL

curl http://localhost:1337/v1/threads/{thread_id}/messages/{message_id} \
  -H "Content-Type: application/json"

Response samples

200

Content type

application/json

{"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699017614,
"thread_id": "thread_abc123",
"role": "user",
"content": [{"type": "text",
"text": {"value": "How does AI work? Explain it in simple terms.",
"annotations": [ ]
}
}
],
"file_ids": [ ],
"assistant_id": null,
"run_id": null,
"metadata": { }
}

Threads

The thread object Webhook

Represents a thread that contains messages. Equivalent to OpenAI's thread object.

Request Body schema: application/json

id	string The identifier of the thread, defaults to foldername.
object	string Type of the object, defaults to thread.
title	string A brief summary or description of the thread, defaults to an empty string.
	Array of objects
created	integer <int64> Unix timestamp representing the creation time of the thread, defaults to file creation time.
metadata	object Metadata associated with the thread, defaults to an empty object.

Request samples

Payload

Content type

application/json

{"id": "thread_....",
"object": "thread",
"title": "funny physics joke",
"assistants": [{"assistant_id": "jan",
"model": {"id": "...",
"settings": { },
"parameters": { }
}
}
],
"created": 1231231,
"metadata": { }
}

Create thread

Create a thread. Equivalent to OpenAI's create thread.

Request Body schema: application/json
optional

object	string Type of the object, indicating it's a thread.
title	string A brief summary or description of the thread, defaults to an empty string.
	Array of objects assistant involved in the thread
metadata	object Metadata associated with the thread, defaults to an empty object.

Responses

Request samples

Payload
cURL
JavaScript
Node.js
Python

Content type

application/json

{"object": "thread",
"title": "funny physics joke",
"assistants": [{"assistant_id": "jan",
"assistant_name": "Jan",
"instructions": "string",
"model": {"id": "mistral-ins-7b-q4",
"settings": { },
"parameters": { },
"engine": "nitro"
}
}
],
"metadata": { }
}

Response samples

200

Content type

application/json

{"id": "thread_abc123",
"object": "thread",
"created_at": 1699014083,
"metadata": { }
}

List threads

Retrieves a list of all threads available in the system.

Responses

Request samples

cURL
JavaScript
Node.js
Python

curl http://localhost:1337/v1/threads \ 
 -H "Content-Type: application/json"

Response samples

200

Content type

application/json

[{"id": "thread_abc123",
"object": "thread",
"created_at": 1699014083,
"assistants": ["assistant-001"
],
"metadata": { },
"messages": [ ]
},
{"id": "thread_abc456",
"object": "thread",
"created_at": 1699014083,
"assistants": ["assistant-002",
"assistant-003"
],
"metadata": { }
}
]

Retrieve thread

Retrieves detailed information about a specific thread using its thread_id. Equivalent to OpenAI's retrieve thread.

path Parameters

thread_id

required

string

The ID of the thread to retrieve.

Responses

Request samples

cURL

curl http://localhost:1337/v1/threads/{thread_id}

Response samples

200

Content type

application/json

{"id": "thread_abc123",
"object": "thread",
"created_at": 1699014083,
"assistants": ["assistant-001"
],
"metadata": { },
"messages": [ ]
}

Modify thread

Modifies a thread. Equivalent to OpenAI's modify thread.

path Parameters

thread_id

required

string

The ID of the thread to be modified.

Request Body schema: application/json
required

title

string

Set the title of the thread

Responses

Request samples

Payload
cURL

Content type

application/json

{"title": "string"
}

Response samples

200

Content type

application/json

{"id": "thread_abc123",
"object": "thread",
"created_at": 1699014083,
"metadata": { }
}

Delete thread

Delete a thread. Equivalent to OpenAI's delete thread.

path Parameters

thread_id

required

string

The ID of the thread to be deleted.

Responses

Request samples

cURL

curl -X DELETE http://localhost:1337/v1/threads/{thread_id}

Response samples

200

Content type

application/json

{"id": "thread_abc123",
"object": "thread.deleted",
"deleted": true
}

API Reference

Introduction

Models

The model object Webhook

Request Body schema: application/json

Request samples

List models

Responses

Request samples

Response samples

Download a specific model.

path Parameters

Responses

Request samples

Response samples

Retrieve model

path Parameters

Responses

Request samples

Response samples

Delete model

path Parameters

Responses

Request samples

Response samples

Chat

Create chat completion

Request Body schema: application/json

Responses

Request samples

Response samples

Assistants

The assistant object Webhook

Request Body schema: application/json

Request samples

List assistants

Responses

Request samples

Response samples

Retrieve assistant

path Parameters

Responses

Request samples

Response samples

Messages

The message object Webhook

Request Body schema: application/json

Request samples

List messages

path Parameters

Responses

Request samples

Response samples

Create message

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Retrieve message

path Parameters

Responses

Request samples

Response samples

Threads

The thread object Webhook

Request Body schema: application/json

Request samples

Create thread

Request Body schema: application/jsonoptional

Responses

Request samples

Response samples

List threads

Responses

Request samples

Response samples

Retrieve thread

path Parameters

Responses

Request Body schema: application/json
required

Request Body schema: application/json
optional

Request Body schema: application/json
required