API
Create chat
Create chat. This applies the validated business action to the selected tenant or platform resource.
/api/chatCreate chat. This applies the validated business action to the selected tenant or platform resource.
Operation IDpostapiChatOperation details
Purpose
Create chat. This applies the validated business action to the selected tenant or platform resource.
When to use it
Use this when the documented business action or resource creation is the intended next step.
When not to use it
Do not repeat the request blindly after an uncertain outcome. Read the resulting resource or background operation state first.
Contract
Availability
- Product version
- Next Product release
- Licence
- An active Product licence is required except for health, authentication, and licence remediation operations.
- Entitlements
- None
- Service roles
- inference
- Deployment
- customer managed installation
- Feature state
- preview
Security
Access
Sign in: Use a session cookie or Bearer session token.
- Actor
- Authenticated Pūnaha actor authorised for the selected tenant and resource
- Permission
- models.read
- Resource
- chat / execute / *
- Tenant rule
- Tenant scoped unless the selected actor is performing an explicitly documented platform action. The x organization id header or authenticated session context selects the tenant. It does not grant access.
- Explicit deny
- An applicable explicit deny overrides an allow. Knowing or supplying a resource identifier never grants access.
Address, query and header fields
| Field | Location | Presence | Type | Meaning | Limits and example |
|---|---|---|---|---|---|
x-request-id | header | Optional | string | Optional caller supplied correlation identifier. Pūnaha returns the effective value in the response header. | Minimum length: 1. Maximum length: 200. Example: example request 001 |
Request body
Content type: application/json. Presence: Required.
Operation request. Every property documents omission, null, sensitivity, source, mutability, availability, access, and lifecycle semantics through JSON Schema and x punaha-* annotations.
Request fields8 documented fields
Request fields
| Field | Presence | Type | Meaning | Empty and default | Limits and example | Access, sensitivity and lifecycle |
|---|---|---|---|---|---|---|
deploymentId | optional | string | Tenant deployment identifier. Takes precedence over model when nonempty. Obtain an identifier from GET /api/models. | Omission or an empty string selects model, then the first tenant deployment. Null is not a documented input. Default: An omitted or empty deploymentId uses model. When both are omitted or empty, the first tenant deployment is used. There is no fixed deployment default. | Example: example deployment id | Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release. |
maxTokens | optional | integer in int64 format | Optional generation token limit. Limits and defaults depend on the selected provider: local llama.cpp uses 512 for values below 1 and caps values above 8192. Anthropic uses at least 1024. Other current adapters send a limit only when it is positive and otherwise leave the provider default in effect. | Omission is decoded as zero. Zero or a negative value uses the provider specific fallback. It does not request a zero length reply. Null is not a documented input. Default: No universal token default. Local llama.cpp uses 512 for omitted or nonpositive values. Anthropic uses 1024. Other adapters use their provider default. | Example: 128 | Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. A generation setting. Do not confuse this field with an authentication token. Lifecycle: Next Product release. |
messages | required | list of ModelsMessageRequest | The messages associated with this resource or operation. | The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present. | Example: example value | Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release. |
messages[].content | required | string | The content associated with this resource or operation. | The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present. | Example: example value | Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. Sensitive. Treat as sensitive. Do not place real values in examples or logs. Apply the Product redaction and access controls. Lifecycle: Next Product release. |
messages[].role | required | string | The role associated with this resource or operation. | The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present. | Example: example value | Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release. |
model | optional | string | Compatibility alias for a tenant deployment identifier, not a provider model name. Used only when deploymentId is omitted or empty. | Omission or an empty string uses the first tenant deployment when deploymentId is also omitted or empty. Null is not a documented input. Default: An omitted or empty deploymentId uses model. When both are omitted or empty, the first tenant deployment is used. There is no fixed deployment default. | Example: example deployment id | Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release. |
stream | optional | boolean | When true, request Server Sent Events from a local llama.cpp deployment. External providers reject streaming with CHAT_STREAMING_UNSUPPORTED before any event is sent. | Omission and false select the ordinary JSON response. Null is not a documented input. Default: No | Example: No | Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release. |
temperature | optional | number in double format or null | Optional sampling temperature passed to the selected provider. An explicit zero is preserved. Provider specific limits and defaults apply. | Omission or null leaves the temperature unspecified. Zero is an explicit value, not omission. Default: No universal temperature default. The selected runtime or provider supplies its default when omitted or null. | Example: 0.2 | Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release. |
Ordinary JSON reply from an explicitly selected deployment
{
"deploymentId": "example-deployment-id",
"maxTokens": 128,
"messages": [
{
"content": "Reply with a short greeting.",
"role": "user"
}
],
"stream": false,
"temperature": 0.2
}Separate streaming request for a local llama.cpp deployment only
{
"deploymentId": "example-local-deployment-id",
"maxTokens": 128,
"messages": [
{
"content": "Reply with a short greeting.",
"role": "user"
}
],
"stream": true
}JSON reply using the first available tenant deployment
{
"messages": [
{
"content": "Reply with a short greeting.",
"role": "user"
}
]
}Responses
| Status | Meaning and correction boundary | Body |
|---|---|---|
200 | The operation completed and the response contains the current operation specific representation. | application/json, ChatResponse or text/event-stream, list of ChatServerSentEvent |
400 | The operation failed with HTTP 400. Inspect error.code and error.details, apply the documented correction, and retain x request id. | application/json, APIError |
401 | The operation failed with HTTP 401. Inspect error.code and error.details, apply the documented correction, and retain x request id. | application/json, APIError |
403 | The operation failed with HTTP 403. Inspect error.code and error.details, apply the documented correction, and retain x request id. | application/json, APIError |
409 | The operation failed with HTTP 409. Inspect error.code and error.details, apply the documented correction, and retain x request id. | application/json, APIError |
423 | The operation failed with HTTP 423. Inspect error.code and error.details, apply the documented correction, and retain x request id. | application/json, APIError |
500 | The operation failed with HTTP 500. Inspect error.code and error.details, apply the documented correction, and retain x request id. | application/json, APIError |
503 | The operation failed with HTTP 503. Inspect error.code and error.details, apply the documented correction, and retain x request id. | application/json, APIError |
200 response fields8 documented fields
200 response fields
| Field | Presence | Type | Meaning | Empty and default | Limits and example | Access, sensitivity and lifecycle |
|---|---|---|---|---|---|---|
data | required | ModelsChatResult | Completed chat result in the ordinary JSON response envelope. | Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present. | No additional schema limit is listed | Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release. |
data.message | required | ModelsMessageResponse | Completed assistant message. | Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present. | No additional schema limit is listed | Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release. |
data.message.content | required | string | Complete generated message text. | Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present. | Example: Hello. | Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release. |
data.message.role | required | string | Role of the message returned by the selected provider. | Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present. | Example: assistant | Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release. |
data.model | required | string | Model identifier reported by the selected runtime or provider. | Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present. | Example: example model | Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release. |
data.performance | optional | object | Optional runtime specific performance measurements, available for local llama.cpp replies. | Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present. | No additional schema limit is listed | Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release. |
data.raw | optional | JSON value | Optional original provider response as JSON. May contain provider specific response details and should follow tenant data handling rules. | Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present. | No additional schema limit is listed | Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release. |
data.usage | optional | object | Optional provider specific token or usage measurements. Field names and availability vary by provider. | Omission, null, an empty value, zero, and false have distinct JSON meanings. Only values permitted by this schema and the operation may be used. Default: No client default is assumed unless a JSON Schema default is present. | No additional schema limit is listed | Inherits the operation access boundary. Shared across documented Pūnaha HTTP operations. No special sensitivity is marked. Do not copy customer content, credentials, or personal information into examples or unsupported logs. Lifecycle: Next Product release. |
Completed ordinary JSON reply
{
"data": {
"message": {
"content": "Hello.",
"role": "assistant"
},
"model": "example-model",
"usage": {
"completionTokens": 2,
"promptTokens": 12
}
}
}200 response fields0 documented fields
200 response fields
ChatServerSentEvent. Parsed chat SSE frame. Decode its data string as JSON using the schema selected by event. The handler emits no id or retry fields and provides no replay protocol.
Final ChatResult without an ordinary data envelope
{
"data": "{\"model\":\"example-model\",\"message\":{\"role\":\"assistant\",\"content\":\"Hello.\"}}",
"event": "chat.completed"
}An incremental text fragment
{
"data": "{\"content\":\"Hello.\"}",
"event": "chat.delta"
}Terminal failure after a partial reply
{
"data": "{\"error\":{\"code\":\"CHAT_STREAM_FAILED\",\"message\":\"Chat generation did not complete.\"}}",
"event": "chat.failed"
}Effects
Behaviour and other effects
- Changes
- Validates access and input, then applies the operation specific state change. A failed validation or authorisation check does not intentionally apply the requested change.
- Audit events
- The mutation is subject to the Product audit policy. The exact event name is operation owned and must be reviewed before publication.
- Background work
- No background work is inferred. The success response represents completion of the HTTP action.
- External effects
- No external call is inferred from the route name. Operation specific service behaviour remains authoritative.
- Transaction boundary
- The HTTP success or error describes the synchronous boundary. Background operations have their own observable lifecycle and may outlive the request.
Operation
Reliability
- Idempotent
- No
- Retry
- Do not retry automatically after a timeout or lost response. Read current state first.
- Concurrency
- Use documented If Match or resource revision fields where exposed. Otherwise read current state before changing it and handle HTTP 409 conflicts.
- Consistency
- The response reflects the synchronous operation boundary. Background and provider backed state can converge later and must be read through its status operation.
- Timeout
- Client timeouts do not cancel completed or already started server work unless the operation explicitly supports cancellation.
- Request ID
- Send or record x request id and retain the returned value for diagnosis.
Errors and corrections
| Status | Code | Cause | Correction | Retryable | Partial work |
|---|---|---|---|---|---|
400 | CHAT_STREAMING_UNSUPPORTED | Streaming is currently supported for local llama.cpp deployments only. Omit stream or set it to false for an external provider. | Correct the named field or rule in error.details, then submit a new request. Retrying an unchanged request will not help. | No unchanged retry | No requested mutation is expected before this failure boundary. |
400 | INVALID_REQUEST_BODY | The request body or supplied field values are invalid. | Correct the named field or rule in error.details, then submit a new request. Retrying an unchanged request will not help. | No unchanged retry | No requested mutation is expected before this failure boundary. |
400 | MODEL_REQUIRED | deploymentId is required when no deployment exists. | Correct the named field or rule in error.details, then submit a new request. Retrying an unchanged request will not help. | No unchanged retry | No requested mutation is expected before this failure boundary. |
401 | AUTHENTICATION_REQUIRED | A valid authenticated session or supported token is required. | Authenticate again using a supported mechanism and confirm that the credential is current. | No unchanged retry | No requested mutation is expected before this failure boundary. |
403 | PERMISSION_REQUIRED | The authenticated actor does not have the exact permission or resource action. | Select the correct tenant and resource, then ask an authorised administrator to grant the exact documented action if appropriate. | No unchanged retry | No requested mutation is expected before this failure boundary. |
409 | STATE_CONFLICT | Current resource state or a dependency prevents the requested change. | Read current state, resolve the named dependency or lifecycle conflict, and submit a deliberate new request. | No unchanged retry | The caller must read current resource or background operation state before retrying because work may have started before the failure became observable. |
423 | LICENCE_REMEDIATION_REQUIRED | The installation is restricted and permits only licence remediation actions. | Complete the indicated licence or membership remediation before retrying Product work. | No unchanged retry | The caller must read current resource or background operation state before retrying because work may have started before the failure became observable. |
500 | INTERNAL_ERROR | Pūnaha could not complete the operation because of an unexpected internal failure. | Retain x request id and the stable error code, avoid blind retries, and investigate the operation or contact support. Code: INTERNAL_ERROR. | No unchanged retry | The caller must read current resource or background operation state before retrying because work may have started before the failure became observable. |
503 | DEPENDENCY_UNAVAILABLE | A required node, database, provider, or service is temporarily unavailable. | Retain x request id, check health and the named dependency, then retry with bounded backoff when safe. | Yes, with the documented safeguards | The caller must read current resource or background operation state before retrying because work may have started before the failure became observable. |
Code examples
Use a supported credential and synthetic data. Do not disable TLS checks or retry a request that changes state blindly.
curl --request POST "$PUNAHA_URL/api/chat" \
--header "Authorization: Bearer $PUNAHA_TOKEN" \
--header "x-request-id: example-request-001" \
--header "Content-Type: application/json" \
--data '{"deploymentId":"example-deployment-id","maxTokens":128,"messages":[{"content":"Reply with a short greeting.","role":"user"}],"stream":false,"temperature":0.2}'const response = await fetch(`${PUNAHA_URL}/api/chat`, {
method: "POST",
headers: {
"x-request-id": "example-request-001",
"Authorization": "Bearer ${PUNAHA_TOKEN}",
"Content-Type": "application/json"
},
body: JSON.stringify({
"deploymentId": "example-deployment-id",
"maxTokens": 128,
"messages": [
{
"content": "Reply with a short greeting.",
"role": "user"
}
],
"stream": false,
"temperature": 0.2
})
});
if (!response.ok) throw new Error(`Punaha request failed: ${response.status}`);
const result = response.status === 204 ? undefined : await response.json();using System.Net.Http.Headers;
using System.Text;
using var client = new HttpClient { BaseAddress = new Uri(punahaUrl) };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", punahaToken);
using var request = new HttpRequestMessage(HttpMethod.Post, "/api/chat");
request.Headers.Add("x-request-id", "example-request-001");
var json = "{\"deploymentId\":\"example-deployment-id\",\"maxTokens\":128,\"messages\":[{\"content\":\"Reply with a short greeting.\",\"role\":\"user\"}],\"stream\":false,\"temperature\":0.2}";
request.Content = new StringContent(json, Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();$headers = @{ Authorization = "Bearer $env:PUNAHA_TOKEN"; "x-request-id" = "example-request-001" }
$body = @'
{
"deploymentId": "example-deployment-id",
"maxTokens": 128,
"messages": [
{
"content": "Reply with a short greeting.",
"role": "user"
}
],
"stream": false,
"temperature": 0.2
}
'@
Invoke-RestMethod -Method POST `
-Uri "$env:PUNAHA_URL/api/chat" `
-Headers $headers `
-ContentType "application/json" `
-Body $bodyRelated APIs
deleteapiModelProvidersConnectionsConnectionId, same domaindeleteapiModelProvidersDeploymentsDeploymentId, same domaingetapiModelProvidersConnections, read or monitorgetapiModelProvidersConnectionsConnectionId, read or monitorgetapiModelProvidersConnectionsConnectionIdModels, read or monitorgetapiModelProvidersDeployments, read or monitor
Version history
- Next Product release: Operation documented from the current registered Go route and handler contract.
Was this page helpful?
Your answer helps us improve the documentation.
Do not include personal information, customer information, passwords, or keys.