> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anannas.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Basic Usage
> Learn the fundamentals of making requests with the Responses API.
This guide covers the basics of using the Anannas Responses API, including simple text requests, conversation management, and handling responses.
**Stateless API**
The Anannas Responses API is **stateless**. Each request is independent and no conversation state is stored server-side. You must include the full conversation history in every request to maintain context.
### Simple Text Request
The simplest way to use the Responses API is with a plain text string:
```python Python theme={null}
import requests
response = requests.post(
"https://api.anannas.ai/api/v1/responses",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json",
},
json={
"model": "openai/gpt-5-mini",
"input": "What is the capital of France?",
"max_output_tokens": 1000,
},
)
result = response.json()
print(result["output"][0]["content"][0]["text"])
```
```typescript TypeScript theme={null}
const response = await fetch('https://api.anannas.ai/api/v1/responses', {
method: 'POST',
headers: {
'Authorization': 'Bearer ',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'openai/gpt-5-mini',
input: 'What is the capital of France?',
max_output_tokens: 1000,
}),
});
const result = await response.json();
console.log(result.output[0].content[0].text);
```
```bash cURL theme={null}
curl https://api.anannas.ai/api/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"model": "openai/gpt-5-mini",
"input": "What is the capital of France?",
"max_output_tokens": 1000
}'
```
### Structured Message Input
For more control, use structured message format with conversation history:
```python Python theme={null}
import requests
response = requests.post(
"https://api.anannas.ai/api/v1/responses",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json",
},
json={
"model": "openai/gpt-5-mini",
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "What is the capital of France?"
}
]
}
],
"max_output_tokens": 1000,
},
)
result = response.json()
print(result["output"][0]["content"][0]["text"])
```
```typescript TypeScript theme={null}
const response = await fetch('https://api.anannas.ai/api/v1/responses', {
method: 'POST',
headers: {
'Authorization': 'Bearer ',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'openai/gpt-5-mini',
input: [
{
type: 'message',
role: 'user',
content: [
{
type: 'input_text',
text: 'What is the capital of France?',
},
],
},
],
max_output_tokens: 1000,
}),
});
const result = await response.json();
console.log(result.output[0].content[0].text);
```
### Multi-Turn Conversations
**Important: Stateless Design**
The Anannas Responses API is **stateless** - it does not maintain conversation state between requests. Unlike OpenAI's stateful Responses API, you must include the complete conversation history in every request. Each request is treated as independent.
Since the API is stateless, you must include the full conversation history in each request:
```python Python theme={null}
import requests
# First request
first_response = requests.post(
"https://api.anannas.ai/api/v1/responses",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json",
},
json={
"model": "openai/gpt-5-mini",
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "What is the capital of France?"
}
]
}
],
"max_output_tokens": 1000,
},
)
first_result = first_response.json()
assistant_message = first_result["output"][0]
# Second request - include previous conversation
second_response = requests.post(
"https://api.anannas.ai/api/v1/responses",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json",
},
json={
"model": "openai/gpt-5-mini",
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "What is the capital of France?"
}
]
},
{
"type": "message",
"role": "assistant",
"status": "completed",
"content": assistant_message["content"]
},
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "What is the population of that city?"
}
]
}
],
"max_output_tokens": 1000,
},
)
second_result = second_response.json()
print(second_result["output"][0]["content"][0]["text"])
```
```typescript TypeScript theme={null}
// First request
const firstResponse = await fetch('https://api.anannas.ai/api/v1/responses', {
method: 'POST',
headers: {
'Authorization': 'Bearer ',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'openai/gpt-5-mini',
input: [
{
type: 'message',
role: 'user',
content: [
{
type: 'input_text',
text: 'What is the capital of France?',
},
],
},
],
max_output_tokens: 1000,
}),
});
const firstResult = await firstResponse.json();
const assistantMessage = firstResult.output[0];
// Second request - include previous conversation
const secondResponse = await fetch('https://api.anannas.ai/api/v1/responses', {
method: 'POST',
headers: {
'Authorization': 'Bearer ',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'openai/gpt-5-mini',
input: [
{
type: 'message',
role: 'user',
content: [
{
type: 'input_text',
text: 'What is the capital of France?',
},
],
},
{
type: 'message',
role: 'assistant',
status: 'completed',
content: assistantMessage.content,
},
{
type: 'message',
role: 'user',
content: [
{
type: 'input_text',
text: 'What is the population of that city?',
},
],
},
],
max_output_tokens: 1000,
}),
});
const secondResult = await secondResponse.json();
console.log(secondResult.output[0].content[0].text);
```
### Using Instructions
You can provide system-level instructions to guide the model's behavior:
```python Python theme={null}
import requests
response = requests.post(
"https://api.anannas.ai/api/v1/responses",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json",
},
json={
"model": "openai/gpt-5-mini",
"input": "Explain quantum computing in simple terms.",
"instructions": "You are a helpful science teacher. Explain concepts clearly and use analogies when helpful.",
"max_output_tokens": 2000,
},
)
result = response.json()
print(result["output"][0]["content"][0]["text"])
```
```typescript TypeScript theme={null}
const response = await fetch('https://api.anannas.ai/api/v1/responses', {
method: 'POST',
headers: {
'Authorization': 'Bearer ',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'openai/gpt-5-mini',
input: 'Explain quantum computing in simple terms.',
instructions: 'You are a helpful science teacher. Explain concepts clearly and use analogies when helpful.',
max_output_tokens: 2000,
}),
});
const result = await response.json();
console.log(result.output[0].content[0].text);
```
### Handling Responses
The response contains an `output` array with one or more output items. Each item has:
* `type`: The type of output (usually "message")
* `role`: The role of the message (usually "assistant")
* `status`: The status of the output ("completed", "incomplete", etc.)
* `content`: An array of content parts
**Extracting Text Content:**
```python Python theme={null}
result = response.json()
# Get the first output item
output_item = result["output"][0]
# Extract text from content
for content_part in output_item["content"]:
if content_part["type"] == "output_text":
print(content_part["text"])
```
```typescript TypeScript theme={null}
const result = await response.json();
// Get the first output item
const outputItem = result.output[0];
// Extract text from content
for (const contentPart of outputItem.content) {
if (contentPart.type === 'output_text') {
console.log(contentPart.text);
}
}
```
### Error Handling
Always check for errors in the response:
```python Python theme={null}
response = requests.post(
"https://api.anannas.ai/api/v1/responses",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json",
},
json={
"model": "openai/gpt-5-mini",
"input": "Hello!",
},
)
if response.status_code != 200:
error = response.json()
print(f"Error: {error['error']['message']}")
else:
result = response.json()
print(result["output"][0]["content"][0]["text"])
```
```typescript TypeScript theme={null}
const response = await fetch('https://api.anannas.ai/api/v1/responses', {
method: 'POST',
headers: {
'Authorization': 'Bearer ',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'openai/gpt-5-mini',
input: 'Hello!',
}),
});
if (!response.ok) {
const error = await response.json();
console.error(`Error: ${error.error.message}`);
} else {
const result = await response.json();
console.log(result.output[0].content[0].text);
}
```
### Best Practices
1. **Always include conversation history**: Since the Anannas API is stateless, include all previous messages in each request. The Anannas API does not remember previous conversations.
2. **Manage state client-side**: You are responsible for maintaining conversation history and including it in each request.
3. **Set appropriate token limits**: Use `max_output_tokens` to control response length
4. **Handle errors gracefully**: Check response status codes and error messages
5. **Use structured input**: Prefer structured message format for better control and multimodal support
6. **Monitor usage**: Check the `usage` field in responses to track token consumption
**Stateless vs Stateful**
OpenAI's Responses API has both stateless and stateful versions. Anannas implements only the **stateless version**, which means:
* No server-side conversation state
* No `previous_response_id` parameter support
* You must include full conversation history in each request
* Each request is completely independent