brevetex
Sign in

Brevetex API Documentation

Complete API reference for integrating Brevetex into your applications.

Introduction

The Brevetex API provides a simple, powerful interface for summarizing content and improving text. All endpoints return JSON responses and use standard HTTP status codes.

Base URL:

https://api.brevetex.com

API Version:

v1

Response Format:

JSON

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header using the Bearer token format.

Header Format:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

To obtain an API key:

  1. Sign in to your Brevetex account
  2. Navigate to the API Keys section in your dashboard
  3. Create a new API key
  4. Copy the key immediately (it will only be shown once)

OAuth Authentication

OAuth authentication is available for third-party integrations upon request. If you need OAuth support for your application, please email us at [email protected].

Example Request

curl -X POST https://api.brevetex.com/api/v1/summarize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your text here"}'

Endpoints

POST /api/v1/summarize

Summarize text or extract and summarize content from documents. Supports plain text input or file uploads (PDF, DOCX, TXT, images with OCR).

Parameters

Parameter Type Required Description
text string No* Text content to summarize
file file No* File to extract text from and summarize (PDF, DOCX, TXT, images)

* At least one of text or file must be provided.

Response

Success (201 Created):

{
  "summary_text": "Concise summary of the input text...",
  "request_id": "abc123..."
}

Examples

Summarize text:

curl -X POST https://api.brevetex.com/api/v1/summarize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Long customer message or document content that needs to be summarized..."
  }'

Summarize from file:

curl -X POST https://api.brevetex.com/api/v1/summarize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

POST /api/v1/improve

Improve text with enhanced clarity, grammar, and flow. Customize the output language, tone, and add custom instructions.

Parameters

Parameter Type Required Description
text string Yes Text content to improve
language string No Output language: en (English) or es (Spanish). Default: en
tone string No Tone: professional, formal, or casual. Default: professional
instructions string No Custom instructions for text improvement

Response

Success (201 Created):

{
  "improved_text": "Improved version of the input text...",
  "request_id": "abc123..."
}

Example

curl -X POST https://api.brevetex.com/api/v1/improve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Looking into your issue now.",
    "language": "en",
    "tone": "professional",
    "instructions": "Make it more empathetic and detailed"
  }'

GET /api/v1/account

Retrieve account information associated with your API key.

Response

Success (200 OK):

{
  "email": "[email protected]"
}

Example

curl -X GET https://api.brevetex.com/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

The API uses standard HTTP status codes and returns error information in JSON format.

HTTP Status Codes

Status Code Description
200 OK - Request successful
201 Created - Resource created successfully
400 Bad Request - Missing required parameters or invalid request format
401 Unauthorized - Invalid or missing API key
422 Unprocessable Entity - Validation errors (e.g., invalid parameter values)
500 Internal Server Error - Server error

Error Response Format

Standard error response:

{
  "error": "Error message description",
  "type": "ErrorClass"
}

Validation errors (422):

{
  "errors": {
    "language": ["Language must be 'es' or 'en'"],
    "tone": ["Tone must be 'professional', 'formal', or 'casual'"]
  }
}

Example Error Responses

401 Unauthorized:

{
  "error": "Unauthorized"
}

400 Bad Request:

{
  "error": "Missing required parameter: text",
  "type": "ActionController::ParameterMissing"
}

422 Unprocessable Entity:

{
  "errors": {
    "base": ["Either text or file must be provided"]
  }
}

Widget Integration (brevetex.js)

Embed Brevetex auto-summarization directly into any website. Add two lines of code and start automatically summarizing your content.

Getting Started

Create a widget script in your Dashboard to get your unique script URL.

Quick Start

Add these two lines to any webpage:

<!-- Include your unique widget script -->
<script src="https://brevetex.com/widget/YOUR_TOKEN_HERE.js"></script>

<!-- Use the brevetex-summary tag anywhere -->
<brevetex-summary>
  Your long text content here that needs to be summarized.
  This can be multiple paragraphs of text.
</brevetex-summary>

Widget Attributes

Attribute Type Default Description
cache-key String Auto-generated Unique identifier for caching. Recommended for static content to improve performance.
cache-ttl Number 7 Number of days to cache summaries. Longer = faster loading, fewer API calls.
loading-text String "Loading summary..." Custom text to display while generating the summary.
error-text String "Failed to load summary" Custom text to display if summary generation fails.

Advanced Examples

Custom Cache Key (Recommended for Static Content)

Using a custom cache key allows summaries to be cached and shared across multiple page loads and users:

<brevetex-summary cache-key="homepage-intro-v1">
  Welcome to our company! We've been innovating since 2020...
</brevetex-summary>

Custom Cache TTL

Set a longer cache duration for content that rarely changes:

<brevetex-summary cache-key="terms-of-service" cache-ttl="30">
  [Your terms of service text...]
</brevetex-summary>

Custom Loading Messages

<brevetex-summary 
  loading-text="Generating summary..." 
  error-text="Unable to generate summary">
  [Your text content...]
</brevetex-summary>

Domain Restrictions

When creating a widget script, specify which domains are allowed to use it (one per line):

  • Exact domain: example.com - Only works on example.com
  • Wildcard subdomains: *.example.com - Works on all subdomains (app.example.com, blog.example.com, etc.)
  • Any domain: * - Works on any domain

Security Note

Using * allows any website to consume your API quota. Only use this for public widgets or testing environments.

How Caching Works

The widget automatically caches summaries to provide the best performance and minimize API usage:

Browser Cache

  • Default: 7 days (configurable with cache-ttl)
  • Instant loading for returning visitors
  • No network requests needed
  • Per-visitor caching

Server Cache

  • Default: 30 days
  • Fast response (~50-200ms)
  • No API quota usage for cached content
  • Shared across all visitors with the same cache key

Performance Benefits

What to expect:

  • Cached in browser: Instant (no network request)
  • Cached on server: ~50-200ms (no quota used)
  • First request: ~2-5s (uses API quota)

Tip: Use Custom Cache Keys

For static content like "About Us" pages or terms of service, always use custom cache keys. This allows summaries to be shared across all visitors, significantly reducing your API costs and improving performance.

Real-World Examples

Example 1: Blog Post Summary

Automatically display a TL;DR at the top of your blog posts:

<article>
  <h1>Understanding Machine Learning in 2026</h1>
  
  <div class="tldr">
    <strong>TL;DR:</strong>
    <brevetex-summary cache-key="blog-ml-2026">
      [Your full blog post content here...]
      Machine learning has evolved significantly...
      [Rest of article...]
    </brevetex-summary>
  </div>
  
  <div class="article-body">
    [Your full blog post content here...]
  </div>
</article>

Example 2: Terms of Service Summary

Help users understand lengthy legal documents:

<div class="legal-summary card">
  <h3>Quick Summary</h3>
  <brevetex-summary 
    cache-key="tos-v2.1" 
    cache-ttl="90"
    loading-text="Generating summary...">
    [Your full terms of service text...]
  </brevetex-summary>
</div>

<div class="full-terms">
  <h2>Full Terms of Service</h2>
  [Your full terms text...]
</div>

Example 3: Product Description Summaries

E-commerce product pages with quick overviews:

<div class="product">
  <h2>Premium Wireless Headphones</h2>
  
  <div class="quick-overview">
    <h4>Quick Overview</h4>
    <brevetex-summary cache-key="product-headphones-pro-2026">
      [Full product description...]
      Experience studio-quality sound with our Premium Wireless
      Headphones. Featuring active noise cancellation, 40-hour
      battery life, premium leather cushions...
      [Rest of detailed specs and features...]
    </brevetex-summary>
  </div>
  
  <details>
    <summary>Full Specifications</summary>
    [Detailed specs...]
  </details>
</div>

Example 4: Documentation Pages

Add summaries to technical documentation:

<div class="doc-page">
  <h1>Getting Started with Our API</h1>
  
  <div class="doc-summary alert alert-info">
    <strong>Page Summary:</strong>
    <brevetex-summary cache-key="docs-api-getting-started-v3">
      [Full documentation content...]
    </brevetex-summary>
  </div>
  
  <div class="doc-content">
    [Full documentation...]
  </div>
</div>

Example 5: Dynamic Content (User-Generated)

For content that changes frequently, let the widget auto-generate cache keys:

<div class="user-review">
  <h4>Customer Review by @jane_doe</h4>
  
  <!-- No cache-key = auto-generated based on content hash -->
  <brevetex-summary cache-ttl="3">
    I've been using this product for 6 months now and here's
    my detailed experience. First, the build quality is 
    exceptional... [Long review continues...]
  </brevetex-summary>
  
  <details>
    <summary>Read Full Review</summary>
    [Full review text...]
  </details>
</div>

Framework Integration

React / Next.js

// Add script to _document.js or layout.js
<Script src="https://brevetex.com/widget/YOUR_TOKEN.js" />

// Use in any component
export default function BlogPost({ content }) {
  return (
    <article>
      <div className="summary">
        <brevetex-summary cache-key={`post-${content.id}`}>
          {content.body}
        </brevetex-summary>
      </div>
    </article>
  );
}

Vue / Nuxt

<!-- Add to nuxt.config.js or main layout -->
<script src="https://brevetex.com/widget/YOUR_TOKEN.js"></script>

<!-- Use in components -->
<template>
  <div class="blog-post">
    <brevetex-summary :cache-key="`post-${postId}`">
      {{ fullContent }}
    </brevetex-summary>
  </div>
</template>

WordPress

<!-- Add to theme's header.php or functions.php -->
<?php
// In functions.php
function add_brevetex_widget() {
    wp_enqueue_script(
        'brevetex-widget',
        'https://brevetex.com/widget/YOUR_TOKEN.js',
        array(),
        null,
        true
    );
}
add_action('wp_enqueue_scripts', 'add_brevetex_widget');
?>

<!-- In your post template -->
<brevetex-summary cache-key="post-<?php the_ID(); ?>">
    <?php the_content(); ?>
</brevetex-summary>

Best Practices

✓ DO: Use custom cache keys for static content

Pages like "About Us", legal docs, or product descriptions that rarely change should always have custom cache keys.

✓ DO: Version your cache keys

When content changes, update the cache key (e.g., homepage-v1 → homepage-v2) to invalidate old caches.

✓ DO: Restrict domains in production

Always specify exact domains or wildcard patterns to prevent unauthorized usage of your quota.

⚠ DON'T: Summarize extremely short text

Text under ~100 characters may not benefit from summarization and will still count toward your quota.

⚠ DON'T: Use * for production domains

Allowing any domain exposes your quota to abuse. Only use * for development or truly public widgets.

Troubleshooting

Issue Solution
Widget shows "No text content found" Ensure there's text content inside the <brevetex-summary> tags.
CORS errors in console Check that your domain is listed in the widget's allowed origins. Ensure you're using the correct protocol (http/https).
Widget not rendering Verify the script URL is correct and accessible. Check browser console for errors.
Summaries not updating after content change Update the cache key version (e.g., v1 → v2) or wait for the cache to expire. Clear your browser cache for immediate testing.
Hitting quota limits too fast Ensure you're using custom cache keys for static content. Check widget usage stats in your dashboard.

Managing Widget Scripts

Manage your widget scripts in the Widget Scripts dashboard:

  • Create unlimited widget scripts
  • Track usage statistics per widget
  • Update allowed domains at any time
  • Activate/deactivate widgets without deleting them
  • Delete widgets to revoke access instantly
  • Monitor last usage timestamp and request counts

Questions or Issues?

If you run into any problems or have feature requests for the widget, please reach out at [email protected].

Need help? Contact us at [email protected]