> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finkkle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Finkkle Spaces Stream API: POST /api/spaces/stream

> Reference for POST /api/spaces/stream — the Finkkle Spaces streaming conversation API. Send conversation history, receive a synthesized AI response with tool execution.

<Warning>
  **Finkkle One is currently undergoing a major overhaul.** The Spaces stream API is disabled until further notice. Finkkle Trends remains accessible. More details soon.
</Warning>

The Spaces stream API powers the Finkkle Spaces AI conversation experience. Send a conversation history and receive a streaming AI response — with tool execution and source synthesis happening automatically behind the scenes, orchestrated by the Spaces planning model.

## POST /api/spaces/stream

```bash theme={null}
POST https://api.finkkle.com/api/spaces/stream
Content-Type: application/json
Authorization: Bearer <your-api-key>
```

### Request body

```json theme={null}
{
  "history": [
    { "role": "user", "content": "What are the latest developments in fusion energy?" }
  ]
}
```

<ParamField body="history" type="array" required>
  Array of conversation turns in order. Each entry has a `role` and `content`.

  <Expandable title="Message object">
    <ResponseField name="role" type="string">
      Either `"user"` or `"assistant"`.
    </ResponseField>

    <ResponseField name="content" type="string">
      The message text.
    </ResponseField>
  </Expandable>
</ParamField>

### Multi-turn conversation

To continue a conversation, include the full history:

```json theme={null}
{
  "history": [
    { "role": "user", "content": "Explain transformer architecture" },
    { "role": "assistant", "content": "Transformers use self-attention mechanisms..." },
    { "role": "user", "content": "Now explain how it differs from an RNN" }
  ]
}
```

### Response

The endpoint returns a streaming text response. The model may execute tools (search, retrieval, calculation) transparently and synthesize results into the final response.

```javascript theme={null}
const res = await fetch('https://api.finkkle.com/api/spaces/stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.FINKKLE_API_KEY}`,
  },
  body: JSON.stringify({
    history: [
      { role: 'user', content: 'Find the latest iPhone 16 prices and summarize them' }
    ]
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}
```

## Integration notes

* **Include full history** — the model has no memory between requests. Always send the complete conversation history for multi-turn interactions.
* **Set timeouts** — the Spaces stream can run for several seconds on complex queries. Set a timeout of at least 30 seconds.
* **Log request IDs** — capture the request ID from the response headers for debugging.
* **Sanitize inputs** — validate and normalize user inputs before sending. Never forward raw, unvalidated user input directly to the API in a production application.

<Warning>
  Do not include passwords, API keys, or sensitive personal data in the conversation history you send to the API. Treat the Spaces stream endpoint like any other AI service — keep credentials and secrets out of prompts.
</Warning>

## Use cases

| Use case              | Approach                                                                   |
| --------------------- | -------------------------------------------------------------------------- |
| In-app AI assistant   | Send user messages as `role: user`, display streamed response              |
| Research tool         | Send a research question; Spaces synthesizes from multiple sources         |
| Document Q\&A         | Include document content in the first user turn as context                 |
| Conversational search | Combine with `GET /api/v1/search` to enrich AI responses with live results |