About Describely's API Logic and Tokens
In this article
- How the API fits Into Describely
- Core API capabilities
- The token model explained
- API vs. UI product usage
- Best practices for integrating with the API
How the API fits Into Describely
Think of the Describely API as the bridge between your content engine and your business systems—like your Product Information Management (PIM) or sales platform.
Instead of generating content only inside the Describely app, the API allows you to programmatically push and pull data from your catalog. You can:
- Create, read, update, and delete (CRUD) product records.
- Retrieve catalogs or apply specific content rulesets for content generation.
- Automate product description creation for configured fields.
In short, the API mirrors Describely’s UI capabilities but gives you the flexibility to scale them automatically through your own systems.
Core API capabilities
Here’s a breakdown of what the API can do for your business:
- Product CRUD Operations: Build, modify, or remove product entries in Describely.
- Catalog Access: Sync product data with your internal catalog so it’s always up to date.
- Ruleset Access: Apply brand voice, tone, and keyword settings to keep generated content consistent. These rulesets must be created in Describely first.
- Content Generation: Generate descriptions, meta titles and meta descriptions, and other configured content fields programmatically.
Example: You can connect your PIM to Describely, send a batch of new products, and get fully optimized descriptions back—without touching the UI.
The token model explained
Describely uses a token-based system to measure API usage and manage billing efficiently.
Each API action—like generating product content—consumes "tokens" based on the size and complexity of the request. These are separate from Describely's UI product credits.
- Pricing: $0.20 per 1,000 tokens
- Typical request cost: 1,000–3,000 tokens per product generation
- Tracking: Your token usage and balance are visible in Account > Plans.
Tokens reflect the processing cost of your request. The more text generated or fields populated, the more tokens used.
Tip: Use the response metadata in API calls to track token usage programmatically for internal reporting or cost control.
API vs. UI product usage
Describely keeps API tokens and UI product credits separate for clarity and accounting purposes.
| Usage Type | Where It Applies | Token Pool | Typical Actions |
|---|---|---|---|
| Product Credits | Inside the Describely app | UI Product credit balance | Generating multiple fields in Describely per product |
| API Tokens | External systems via API | API token balance | Automated content generation, product creation, etc. |
This separation ensures you can scale integrations or automation without impacting your day-to-day content creation balance and UI activities in Describely.
Note: Token usage in staging and production environments is tracked independently. Always verify which environment your key is linked to.
Best practices for integrating with the API
A few key recommendations to get the most out of Describely’s API:
- Use Environment Variables: Store API keys securely—never hardcode them.
- Monitor Usage Regularly: Check your Account > Plans dashboard to prevent unexpected overages.
- Keep Environments Separate: Use distinct keys for staging and production to isolate data safely.
- Apply Rulesets Programmatically: Automate brand consistency by referencing your ruleset IDs in generation requests.
Tip: Treat the API as part of your content workflow, not a separate tool. Integrating it with your PIM or eCommerce backend lets you automate content creation, publishing, and updates seamlessly.
Ready to get started? Check out this step-by-step tutorial to get set up on Describely's API.