Name: Tuatara Summarize API: Extractive Text Summarization
Brand: cymetica
SKU: api-cymetica-tuatara-summarize
Availability: InStock
Author: API Market

# Tuatara Summarize API

## Overview

Tuatara Summarize is an extractive summarization model by Cymetica. You send a document and it returns the sentences that carry its meaning, in the length you choose. Every sentence in the summary is a sentence from the input, so the summary never contains a claim the document did not make. `/summarize` takes the text directly and returns the summary with sentence positions, scores and keywords, `/chat/completions` accepts the OpenAI chat format, and `/models`, `/health` and `/usage` describe the model, its status and metered usage.

It is built for developers of AI agents, RAG pipelines, news and finance feeds, and review tools that need a short, quotable version of a long text. Because it ranks sentences instead of generating new ones, it is fast, cheap and auditable: every output sentence can be found in the source.

## Features

*   **5 endpoints**: a plain summarize call, an OpenAI-compatible chat completions call, and model, health and usage endpoints.
*   **Extractive**: output sentences are taken verbatim from the input and returned in document order by default.
*   **Length control**: choose a sentence count, a share of the document (`ratio`) or a token budget (`max_tokens`).
*   **Topic steering**: `context_control` takes one word that steers the summary toward a subject.
*   **Large inputs**: plain text or HTML up to 200,000 tokens per document.
*   **Sentence scores**: `/summarize` returns the index and score of every selected sentence plus keywords.
*   **Rate limit**: 10 requests per second on the pay-as-you-go plan.

## Use Cases

*   **RAG pipelines**: shorten retrieved passages before they go into a prompt, without adding invented context.
*   **AI agents**: give an agent a grounded brief of a filing, article or transcript that it can quote.
*   **News and finance feeds**: turn long articles into a three-sentence item for a dashboard or alert.
*   **Review queues**: show reviewers the key sentences so they can triage without opening every document.
*   **Highlighting**: use the returned sentence indexes to highlight the important lines in the original text.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/cymetica/tuatara-summarize
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Summarize a document

Returns the summary text plus the index and score of each selected sentence, the top keywords and token usage. With no length option, two sentences are returned.

**Method:** `POST`

**Endpoint:** `/summarize`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `model` | body | Model id: `tuatara-summarize-1.0` or `tuatara-summarize-latest`. | string | No | `tuatara-summarize-latest` | - |
| `sentence_count` | body | Sentences to keep (1-5 in faithful mode) | integer | No | - | 500 |
| `ratio` | body | Share of the document's sentences to keep | number | No | - | 0.9 |
| `max_tokens` | body | Token budget for the summary (cl100k tokens) | integer | No | - | 200000 |
| `context_control` | body | One word that steers the summary toward a subject | string | No | - | - |
| `context_control_sensitivity_level` | body | How strongly `context_control` steers the summary, from 0 to 10. | number | No | `2` | 10 |
| `mode` | body | auto picks the best measured engine for the document's size; faithful is the original 2015 algorithm | string | No | `auto` | - |
| `order` | body | Sentences in document order, or best first | string | No | `document` | - |
| `output` | body | json adds the original v0.1 response shape | string | No | `text` | - |
| `text` | body | The document, plain text or HTML, up to 1.5 million characters / 200,000 tokens | string | Yes | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/cymetica/tuatara-summarize/summarize' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "The James Webb Space Telescope captured a new image of the Pillars of Creation. The pillars are columns of cool gas and dust in the Eagle Nebula, about 6,500 light-years from Earth. New stars are forming inside them. The image shows thousands of stars that were hidden in earlier pictures because dust blocks visible light. Webb sees in infrared, which passes through the dust. Astronomers will use the image to count newly formed stars and measure the gas left in the pillars. Over the next few million years the pillars will slowly erode as radiation from nearby young stars blows the gas away. The new data will help refine models of how stars form in dense clouds. NASA released the image together with the European and Canadian space agencies.",
  "ratio": 0.3
}'
```

**Example Response (200 OK):**

```json
{
  "id": "sum-f98a3ed4bb9264233aa970c7",
  "object": "summary",
  "created": 1793521619,
  "model": "tuatara-summarize-latest",
  "mode": "tuned-best",
  "text": "The James Webb Space Telescope captured a new image of the Pillars of Creation. The pillars are columns of cool gas and dust in the Eagle Nebula, about 6,500 light-years from Earth. New stars are forming inside them.",
  "sentences": [
    {
      "index": 1,
      "score": 0.030579
    },
    {
      "index": 2,
      "score": 0.03055
    }
  ],
  "keywords": [
    "star",
    "image"
  ],
  "context_found": false,
  "passthrough": false,
  "usage": {
    "input_tokens": 149,
    "output_tokens": 48
  }
}
```

#### 2. Summarize in OpenAI chat format

Summarizes the last user message and returns a standard chat completion, so OpenAI client libraries work by changing the base URL and model name. The summary is in `choices[0].message.content`.

**Method:** `POST`

**Endpoint:** `/chat/completions`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `model` | body | Model id: `tuatara-summarize-1.0` or `tuatara-summarize-latest`. | string | No | `tuatara-summarize-latest` | - |
| `sentence_count` | body | Sentences to keep (1-5 in faithful mode) | integer | No | - | 500 |
| `ratio` | body | Share of the document's sentences to keep | number | No | - | 0.9 |
| `max_tokens` | body | Token budget for the summary (cl100k tokens) | integer | No | - | 200000 |
| `context_control` | body | One word that steers the summary toward a subject | string | No | - | - |
| `context_control_sensitivity_level` | body | How strongly `context_control` steers the summary, from 0 to 10. | number | No | `2` | 10 |
| `mode` | body | auto picks the best measured engine for the document's size; faithful is the original 2015 algorithm | string | No | `auto` | - |
| `order` | body | Sentences in document order, or best first | string | No | `document` | - |
| `output` | body | json adds the original v0.1 response shape | string | No | `text` | - |
| `messages` | body | Chat messages. The last user message is the document to summarize. | array of objects | Yes | - | - |
| `stream` | body | Stream the response as server-sent events. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/cymetica/tuatara-summarize/chat/completions' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "tuatara-summarize-latest",
  "ratio": 0.3,
  "messages": [
    {
      "role": "user",
      "content": "The James Webb Space Telescope captured a new image of the Pillars of Creation. The pillars are columns of cool gas and dust in the Eagle Nebula, about 6,500 light-years from Earth. New stars are forming inside them. The image shows thousands of stars that were hidden in earlier pictures because dust blocks visible light. Webb sees in infrared, which passes through the dust. Astronomers will use the image to count newly formed stars and measure the gas left in the pillars. Over the next few million years the pillars will slowly erode as radiation from nearby young stars blows the gas away. The new data will help refine models of how stars form in dense clouds. NASA released the image together with the European and Canadian space agencies."
    }
  ]
}'
```

**Example Response (200 OK):**

```json
{
  "id": "chatcmpl-67ce30ce691932ad252e0ebd",
  "object": "chat.completion",
  "created": 1793521621,
  "model": "tuatara-summarize-latest",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "The James Webb Space Telescope captured a new image of the Pillars of Creation. The pillars are columns of cool gas and dust in the Eagle Nebula, about 6,500 light-years from Earth. New stars are forming inside them."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 149,
    "completion_tokens": 48,
    "total_tokens": 197
  }
}
```

#### 3. Get usage

Returns the request and token counts the provider has recorded for API.market traffic, per day.

**Method:** `GET`

**Endpoint:** `/usage`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `days` | query | Number of days of history to return. | integer | No | `30` | 90 |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/cymetica/tuatara-summarize/usage?days=30' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "key": "apimarket",
  "days": [],
  "metering": "available"
}
```

#### 4. Check service health

Returns the model name, whether it is being served, and request and uptime counts for today and the last 7 days.

**Method:** `GET`

**Endpoint:** `/health`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/cymetica/tuatara-summarize/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "model": "tuatara-summarize-1.0",
  "served": true,
  "zero_data_retention": true,
  "uptime_today": {
    "requests": 0,
    "answered": 0,
    "uptime": null
  },
  "uptime_7d": {
    "requests": 1526,
    "answered": 1526,
    "uptime": 1.0
  }
}
```

#### 5. List models

Returns the model document: description, input limits, token pricing, supported parameters and readiness.

**Method:** `GET`

**Endpoint:** `/models`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/cymetica/tuatara-summarize/models' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "schema_version": "2.4",
  "data": [
    {
      "schema_version": "2.4",
      "id": "tuatara-summarize-1.0",
      "name": "Tuatara Summarize 1.0",
      "created": 1793145600,
      "description": "Tuatara Summarize returns an extract of a document: its own sentences, chosen by a vector-association model of the text, in document order, cut to a sentence count, a share of the document or a token...",
      "input_modalities": [
        {
          "type": "text",
          "supported_inputs": {
            "max_context_length": {
              "value": 200000
            },
            "max_prompt_length": {
              "value": 200000
            }
          },
          "pricing": [
            {
              "type": "prompt",
              "unit": "token",
              "cost_usd": "0.0000000048"
            }
          ]
        }
      ],
      "output_modalities": [
        {
          "type": "text",
          "streaming": true,
          "supported_parameters": {
            "max_tokens": {
              "type": "integer",
              "min": 1,
              "max": 200000
            }
          },
          "pricing": [
            {
              "type": "completion",
              "unit": "token",
              "cost_usd": "0.0000000048"
            }
          ]
        }
      ],
      "is_ready": true,
      "quantization": "fp32",
      "tokenizer": "Other",
      "passthrough_parameters": {
        "mode": {
          "type": "enum",
          "values": [
            "auto",
            "faithful"
          ],
          "default": "auto"
        },
        "sentence_count": {
          "type": "integer",
          "min": 1,
          "max": 500
        },
        "max_sentences": {
          "type": "integer",
          "min": 1,
          "max": 500
        },
        "ratio": {
          "type": "range",
          "min": 0.05,
          "max": 0.9
        },
        "context_control": {
          "type": "unknown"
        },
        "context_control_sensitivity_level": {
          "type": "range",
          "min": 0,
          "max": 10,
          "default": 2
        },
        "db": {
          "type": "enum",
          "values": [
            "websters-2009"
          ],
          "default": "websters-2009"
        },
        "order": {
          "type": "enum",
          "values": [
            "document",
            "rank"
          ],
          "default": "document"
        },
        "output": {
          "type": "enum",
          "values": [
            "text",
            "json"
          ],
          "default": "text"
        },
        "faithful": {
          "type": "boolean",
          "default": false
        }
      },
      "datacenters": [
        {
          "country_code": "JP"
        }
      ]
    },
    {
      "schema_version": "2.4",
      "id": "tuatara-summarize-latest",
      "name": "Tuatara Summarize (latest)",
      "created": 1793145600,
      "description": "Tuatara Summarize returns an extract of a document: its own sentences, chosen by a vector-association model of the text, in document order, cut to a sentence count, a share of the document or a token...",
      "input_modalities": [
        {
          "type": "text",
          "supported_inputs": {
            "max_context_length": {
              "value": 200000
            },
            "max_prompt_length": {
              "value": 200000
            }
          },
          "pricing": [
            {
              "type": "prompt",
              "unit": "token",
              "cost_usd": "0.0000000048"
            }
          ]
        }
      ],
      "output_modalities": [
        {
          "type": "text",
          "streaming": true,
          "supported_parameters": {
            "max_tokens": {
              "type": "integer",
              "min": 1,
              "max": 200000
            }
          },
          "pricing": [
            {
              "type": "completion",
              "unit": "token",
              "cost_usd": "0.0000000048"
            }
          ]
        }
      ],
      "is_ready": true,
      "quantization": "fp32",
      "tokenizer": "Other",
      "passthrough_parameters": {
        "mode": {
          "type": "enum",
          "values": [
            "auto",
            "faithful"
          ],
          "default": "auto"
        },
        "sentence_count": {
          "type": "integer",
          "min": 1,
          "max": 500
        },
        "max_sentences": {
          "type": "integer",
          "min": 1,
          "max": 500
        },
        "ratio": {
          "type": "range",
          "min": 0.05,
          "max": 0.9
        },
        "context_control": {
          "type": "unknown"
        },
        "context_control_sensitivity_level": {
          "type": "range",
          "min": 0,
          "max": 10,
          "default": 2
        },
        "db": {
          "type": "enum",
          "values": [
            "websters-2009"
          ],
          "default": "websters-2009"
        },
        "order": {
          "type": "enum",
          "values": [
            "document",
            "rank"
          ],
          "default": "document"
        },
        "output": {
          "type": "enum",
          "values": [
            "text",
            "json"
          ],
          "default": "text"
        },
        "faithful": {
          "type": "boolean",
          "default": false
        }
      },
      "datacenters": [
        {
          "country_code": "JP"
        }
      ]
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | The body is not valid JSON, `text` or `messages` is missing, or a length option is out of range. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but has no active subscription to this API, or your plan quota is used up. |
| 404 | Not Found | The path does not exist. Check the endpoint path against this page. |
| 429 | Too Many Requests | You sent more than your plan's per-second limit (10 requests per second). Wait and retry, honouring the `Retry-After` header when present. |
| 500 | Internal Server Error | An unexpected error on the provider side. Retry after a short wait. |
| 503 | Service Unavailable | The model is temporarily not available. Retry after a short wait. |

## Rate Limits

Each plan has a per-second limit (10 requests per second on the pay-as-you-go plan) and a monthly call quota shown on the pricing page. Requests over the per-second limit get a 429 response. Throttle your client, back off when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **Can the summary contain words that are not in my document?**

    No. The model selects and orders sentences from the input. It does not rewrite or generate text.

*   **How do I choose the summary length?**

    Send one of `sentence_count`, `ratio` (share of the sentences to keep) or `max_tokens`. With none, two sentences are returned.

*   **What does `mode` do?**

    `auto` picks the best engine for the document size. `faithful` is the original algorithm and keeps 1 to 5 sentences. The other modes are alternative engines.

*   **Which endpoint should I use?**

    Use `/summarize` when you want sentence indexes, scores and keywords. Use `/chat/completions` when your code already speaks the OpenAI chat format.

*   **How is it billed?**

    On the pay-as-you-go plan, usage is counted in units of 1,000 tokens (input plus output), with at least one unit per call.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Summarize long text with sentences taken straight from the source, so nothing is invented. OpenAI-compatible, up to 200,000 tokens per document.

Tuatara Summarize API: Extractive Text Summarization

PAYG

Cymetica

Extractive summarization for agents and pipelines: every output sentence is taken from the source, so a summary never invents a claim. OpenAI-compatible.