YourText.Guru API v2 – Developer Guide
Welcome to the YourText.Guru API v2. This API enables developers to integrate SEO optimization tools into their applications, allowing for content analysis, keyword research, and more.
Base URL
Authentication
All API requests require authentication. You must include your API key in the request headers:
Authorization: Bearer YOUR_API_KEY
Replace YOUR_API_KEY with your actual API key.
Rate Limiting
The API enforces rate limits to ensure fair usage. If you exceed the allowed number of requests, you will receive a 429 Too Many Requests response. Monitor your usage and implement appropriate backoff strategies.
Endpoints Overview
1. Status Endpoints
Endpoints for monitoring API availability and usage.
GET /status
Description:
Check the current operational status of the API.
Parameters:
None
GET /consumption/openai
Description:
Retrieve information about OpenAI-related usage and consumption.
Parameters:
- lastId (integer) – Retrieve consumption entries after this ID (for pagination or incremental updates).
2. Project Endpoints
Endpoints for managing SEO projects, including creation, retrieval, and deletion.
GET /projects
Description:
Retrieve a list of all projects associated with the authenticated user.
Parameters:
None
POST /projects
Description:
Create a new project.
Parameters:
- name (string) – Name of the project.
- host (string) – Associated domain or host (e.g., example.com).
GET /projects/{projectId}
Description:
Retrieve detailed information about a specific project.
Parameters:
- projectId (integer) – ID of the project to retrieve.
POST /projects/{projectId}
Description:
Update the name or host of an existing project.
Parameters:
- projectId (integer) – ID of the project to update.
- name (string) – New name for the project.
- host (string) – New host or domain for the project.
DELETE /projects/{projectId}
Description:
Delete a specific project by its ID.
Parameters:
- projectId (integer) – ID of the project to delete.
3. Group Endpoints
Endpoints for organizing guides into groups and generating topical meshes within a project.
GET /projects/{projectId}/groups
Description:
Retrieve all groups within a specific project.
Parameters:
- projectId (integer) – ID of the project.
POST /projects/{projectId}/groups
Description:
Create a new group within a project.
Parameters:
- projectId (integer) – ID of the project.
- name (string) – Name of the new group.
GET /projects/{projectId}/groups/{groupId}
Description:
Retrieve details of a specific group.
Parameters:
- projectId (integer) – ID of the project.
- groupId (integer) – ID of the group.
POST /projects/{projectId}/groups/{groupId}
Description:
Update the name of a specific group.
Parameters:
- projectId (integer) – ID of the project.
- groupId (integer) – ID of the group.
- name (string) – New name for the group.
DELETE /projects/{projectId}/groups/{groupId}
Description:
Delete a specific group from a project.
Parameters:
- projectId (integer) – ID of the project.
- groupId (integer) – ID of the group.
POST /projects/{projectId}/groups/{groupId}/guides/add
Description:
Add a list of guide to a group.
Parameters:
- projectId (integer) – ID of the project.
- groupId (integer) – ID of the group.
- guideId (integer) – ID of the guide to add.
POST /projects/{projectId}/groups/{groupId}/guides/remove
Description:
Remove guides from a group.
Parameters:
- projectId (integer) – ID of the project.
- groupId (integer) – ID of the group.
- guideId (integer) – ID of the guide to remove.
GET /projects/{projectId}/groups/{groupId}/topicalMesh
Description:
Retrieve the topical mesh associated with a group.
Parameters:
- projectId (integer) – ID of the project.
- groupId (integer) – ID of the group.
POST /projects/{projectId}/groups/{groupId}/topicalMesh
Description:
Generate a topical mesh for a group.
Parameters:
- projectId (integer) – ID of the project.
- groupId (integer) – ID of the group.
GET /projects/{projectId}/groups/{groupId}/topicalMesh/wordcloud
Description:
Retrieve a word cloud visualization of the group’s topical mesh.
Parameters:
- projectId (integer) – ID of the project.
- groupId (integer) – ID of the group.
GET /projects/{projectId}/groups/{groupId}/topicalMesh/paa
Description:
Retrieve « People Also Ask » questions related to the group’s topical mesh.
Parameters:
- projectId (integer) – ID of the project.
- groupId (integer) – ID of the group.
4. Guide Endpoints
Endpoints related to the creation, retrieval, and analysis of SEO guides.
GET /guides
Description:
Retrieve a list of guides, optionally filtered by project, group, or other attributes.
Parameters:
- projectId (integer) – ID of the associated project.
- lastId (integer) – Retrieve guides after this ID (for pagination).
- lang (string) – Language code (e.g., » en_GB », » fr_FR »).
- apiOnly (integer) – If set to 1, only API-generated guides are returned.
- groupId (integer) – ID of the associated group.
- status (string) – Filter by guide status.
POST /guides
Description:
Create a new SEO guide based on a query (keyword or phrase).
Parameters:
- query (string) – Target keyword or phrase.
- lang (string) – Language code for the guide.
- projectId (integer) – ID of the project to associate the guide with.
- type (string) – Type of guide (, « google » or « bing »).
- groupId (integer) – group ID to associate the guide with.
GET /guides/{guideId}
Description:
Retrieve detailed information about a specific guide.
Parameters:
- guideId (integer) – ID of the guide to retrieve.
DELETE /guides/{guideId}
Description:
Delete a specific guide by its ID.
Parameters:
- guideId (integer) – ID of the guide to delete.
GET /guides/{guideId}/paa
Description:
Retrieve « People Also Ask » questions related to the guide’s query.
Parameters:
- guideId (integer) – ID of the guide.
GET /guides/{guideId}/related
Description:
Retrieve keywords and topics related to the guide’s query.
Parameters:
- guideId (integer) – ID of the guide.
POST /guides/{guideId}/check
Description:
Check the SEO quality of a given text against the guide.
Parameters:
- guideId (integer) – ID of the guide.
- text (string) – The content to analyze.
GET /guides/{guideId}/serp
Description:
Retrieve SERP (Search Engine Results Page) data related to the guide’s keyword.
Parameters:
- guideId (integer) – ID of the guide.
GET /guides/{guideId}/brief
Description:
Get the current brief associated with the guide.
Parameters:
- guideId (integer) – ID of the guide.
POST /guides/{guideId}/brief
Description:
Generate or update the brief for the guide.
Parameters:
- guideId (integer) – ID of the guide.
GET /guides/{guideId}/brief/analyze
Description:
Retrieve the result of the latest brief analysis.
Parameters:
- guideId (integer) – ID of the guide.
POST /guides/{guideId}/brief/analyze
Description:
Submit a brief for SEO analysis.
Parameters:
- guideId (integer) – ID of the guide.
- requestBody (string) – Text content to analyze.
GET /guides/{guideId}/brief/analyze/{analyzeId}
Description:
Retrieve a specific analysis result by its ID.
Parameters:
- guideId (integer) – ID of the guide.
- analyzeId (integer) – ID of the analysis to retrieve.
5. Seo Txl Endpoints
Endpoints for generating and manipulating SEO-optimized text (TXL) based on guide data.
POST /guides/{guideId}/seotxl/auto
Description:
Automatically generate SEO content based on the guide and input text.
Parameters:
- guide (integer) – ID of the guide.
- text (string) – Input text to base the generation on.
POST /guides/{guideId}/seotxl/outline
Description:
Generate a structured outline for SEO content.
Parameters:
- guide (integer) – ID of the guide.
- text (string) – Input topic or content to guide the outline.
POST /guides/{guideId}/seotxl/questions
Description:
Generate a list of relevant questions based on the guide’s topic.
Parameters:
- guide (integer) – ID of the guide.
POST /guides/{guideId}/seotxl/rephrase
Description:
Rephrase a given text to improve clarity or SEO performance.
Parameters:
- guide (integer) – ID of the guide.
- text (string) – The text to rephrase.
POST /guides/{guideId}/seotxl/create
Description:
Generate custom SEO text with configurable temperature and word limit.
Parameters:
- guide (integer) – ID of the guide.
- text (string) – Input prompt or content base.
- temperature (integer) – Controls creativity (higher = more creative).
- maxWords (integer) – Maximum number of words in the output.
Error Handling
The API uses standard HTTP status codes to indicate success or failure:
200 OK: Request succeeded.
201 Created: Resource created successfully.
400 Bad Request: The request was invalid or cannot be served.
401 Unauthorized: Authentication failed or user does not have permissions.
403 Forbidden: Access to the requested resource is forbidden.
404 Not Found: The requested resource could not be found.
429 Too Many Requests: Rate limit exceeded.
500 Internal Server Error: An error occurred on the server.
Support and Documentation
For more detailed information, refer to the official API documentation: https://yourtext.guru/api/v2/documentation
If you encounter issues or have questions, please contact the YourText.Guru support team through their support portal.