API reference

Batches

Submit asynchronous collections of requests, inspect progress, and cancel eligible work.

How it fits together

01Create a durable JSONL batch
02Request cancellation of queued batch work
03Retrieve one batch and its request counts

Select an action to see its complete inputs, request, response, and status codes.

Create a durable JSONL batch

POST/v1/batches

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Content typeapplication/json

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`Idempotency-Key`	Header	string	Optional	Supported	Replay key for an admitted run; a repeat returns the first result.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`completion_window`	Body	string	Optional	Conditional	The supported completion window; currently 24h.
`endpoint`	Body	string	Required	Supported	The one public endpoint each JSONL line targets.
`input_file_id`	Body	string	Required	Supported	A ready JSONL file uploaded with purpose=batch.
`metadata`	Body	object	Optional	Supported	Caller metadata copied to the batch object.

A compatible model and provider route are required for conditional fields.

Request

curl -X POST 'https://api.mahvashai.ir/v1/batches' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "endpoint": "/v1/embeddings",
  "input_file_id": "file-3f5a8c4e-6b8d-4a4f-9d2c-1f0a2b3c4d5e"
}'

Response

{
  "id": "<id>",
  "object": "batch",
  "endpoint": "<value>",
  "errors": null,
  "input_file_id": "<id>",
  "completion_window": "24h",
  "status": "in_progress",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1750000000,
  "in_progress_at": 0,
  "expires_at": 1750000000,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "test": "<value>"
  }
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Create a durable JSONL batch.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Request cancellation of queued batch work

POST/v1/batches/{batch_id}/cancel

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`batch_id`	Path	string	Required	Supported	The durable batch identifier.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X POST 'https://api.mahvashai.ir/v1/batches/<batch_id>/cancel' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

A representative JSON response is not available for this endpoint. Handle the documented HTTP status and inspect the returned body according to your client workflow.

Status codes

HTTP	Details
200	Request cancellation of queued batch work.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Retrieve one batch and its request counts

GET/v1/batches/{batch_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`batch_id`	Path	string	Required	Supported	The durable batch identifier.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X GET 'https://api.mahvashai.ir/v1/batches/<batch_id>' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "id": "<id>",
  "object": "batch",
  "endpoint": "<value>",
  "errors": null,
  "input_file_id": "<id>",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "<id>",
  "error_file_id": null,
  "created_at": 1750000000,
  "in_progress_at": 0,
  "expires_at": 1750000000,
  "finalizing_at": 0,
  "completed_at": 0,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "test": "<value>"
  }
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Retrieve one batch and its request counts.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

List durable batches in the selected project

GET/v1/batches

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`after`	Query	string	Optional	Supported	Return batches after this ID.
`limit`	Query	integer	Optional	Supported	Number of batches, capped at 100.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X GET 'https://api.mahvashai.ir/v1/batches' \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "<id>",
      "object": "batch",
      "endpoint": "<value>",
      "errors": null,
      "input_file_id": "<id>",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "<id>",
      "error_file_id": null,
      "created_at": 1750000000,
      "in_progress_at": 0,
      "expires_at": 1750000000,
      "finalizing_at": 0,
      "completed_at": 0,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
      },
      "metadata": {
        "test": "<value>"
      }
    }
  ],
  "first_id": "<id>",
  "last_id": "<id>",
  "has_more": false
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	List durable batches in the selected project.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.