# PubConsole API

⚠️ Currently, the API supports forum and Q&A backlinks only. Stay tuned for updates.

Base URL: https://pubconsole.com/api
Authorization: header `Authorization: Bearer <API_KEY>` (get the key in your dashboard)
Content-Type: application/json
Rate limit: 30 requests per second; send requests sequentially, waiting for each response

With the API or MCP, the user controls link placement on their own,
without the PubConsole algorithm: they choose the keywords, link types and placement pace,
or delegate link building strategy planning to an AI agent.

## Creating link tasks
- Before creating tasks, create a project for the website once
- Pass the project ID with every task; the domain in the task must match the project's domain
- Save the task ID and project ID to manage them later
- Websites are selected individually for each task and can't be chosen in advance

## Status tracking
- Check task status no more than once a day
- Turnaround time: from a few hours to a few days

## Guarantee and monitoring
- Moderators review every task
- The link is checked for 30 days (the guarantee period); if it's removed, it's replaced with a similar one
- Sync statuses once a day

## Managing tasks
- Completed work can be rejected within 30 days for a valid reason
- A task can be deleted only while it has the NEW status

## Endpoints

### GET v1/users — Get user info
Returns the balance and account details.
Response: { "userId": 1050, "email": "jane@example.com", "name": "Jane Smith", "balance": 150 }

### POST v1/projects — Create a project
Parameters: url (string, required, http:// or https://), name (string, optional, 1–255 characters), language (string, required)

Supported languages: ENGLISH, SPANISH, GERMAN, JAPANESE, FRENCH, PORTUGUESE, ITALIAN, DUTCH, POLISH, VIETNAMESE

Request: { "url": "https://www.example.com", "name": "Acme Plumbing", "language": "ENGLISH" }
Response: { "status": "Project created successfully", "projectId": 5001 }

### GET v1/projects — List projects
Returns an array of projects: projectId, name, status, domain, language, createdAt, updatedAt

Project statuses:
- ACTIVE — active project
- PENDING — project is under review
- PAUSED — automatic link ordering is turned off
- REJECTED — project was rejected (the reason is in rejectReason)

rejectReason values: Language or region does not match the site, Prohibited content, Technical issues on the site

### GET v1/projects/<projectId>/status — Get project status
Project statuses: ACTIVE, PENDING, PAUSED, REJECTED (the reason is in rejectReason; see the values under GET v1/projects above)
Response: { "projectId": 5001, "status": "ACTIVE", "domain": "example.com", "language": "ENGLISH", "createdAt": "...", "updatedAt": "..." }

### DELETE v1/projects/<projectId> — Delete a project
Only if the project has no active tasks.
Response: { "message": "Project deleted successfully" }

### POST v1/tasks — Create a link task
The price is charged to the balance right away.
Parameters: projectId (number), keyword (string, up to 100 characters), url (string)
Request: { "projectId": 5001, "keyword": "water heater repair", "url": "https://www.example.com/water-heater-repair" }
Response: { "status": "Link task created successfully", "taskId": 20505, "balanceAfter": 140.01 }

### GET v1/tasks/<taskId>/status — Get task status
Task statuses:
- NEW — new task, not started yet
- IN_PROGRESS — task is in progress
- PENDING — task is under moderator review
- REJECTED — task is being reworked
- COMPLETED — task is completed
- DELETED — task was deleted (by an admin or the client)

For deleted tasks (status: DELETED), the response includes a deleteReason field.

deleteReason values: Site is unavailable or blocked, Page has no content, The task cannot be completed on the selected donor, Redirects to another page or site, Language or region does not match the page, Keyword contains an error, Keyword does not match the page, Unable to complete the task due to technical reasons, Task deleted by client (when the client deleted the task), Task deleted, no reason specified (no reason given)

Response: { "taskId": 20505, "projectId": 5001, "status": "COMPLETED", "keyword": "...", "targetUrl": "...", "resultUrl": "...", "price": 9.99, "warrantyUpTo": "...", "createdAt": "...", "updatedAt": "..." }
Response for a deleted task: { "taskId": 20508, "projectId": 5001, "status": "DELETED", "keyword": "water heater repair", "targetUrl": "https://www.example.com/water-heater-repair", "deleteReason": "Page has no content", "createdAt": "...", "updatedAt": "..." }

### GET v1/projects/<projectId>/tasks — List project tasks
Parameters: page (defaults to 1), limit (defaults to 10, max 1,000), status (filter: NEW/IN_PROGRESS/PENDING/REJECTED/COMPLETED/DELETED). Without the status parameter, tasks with all statuses are returned, including DELETED.
Example: GET /v1/projects/5001/tasks?page=1&limit=100&status=NEW

For task statuses and deleteReason values, see GET v1/tasks/<taskId>/status above.

The response contains a tasks array and pagination (currentPage, totalPages, totalCount, limit). The completedAt field is included in a task only if it isn't null.

### PATCH v1/tasks/<taskId>/reject — Reject a completed task
Parameters: reason (string, up to 255 characters)
Request: { "reason": "The link is not clickable. Please fix it." }
Response: { "message": "Link task sent for rework successfully" }

### DELETE v1/tasks/<taskId> — Delete a task
Only for tasks with the NEW status; the amount is refunded to the balance.
Response: { "message": "Link task deleted, funds returned", "balanceAfter": 150 }

## Response codes
- 200 — the request was successful
- 201 — the project or task was created successfully
- 400 — invalid request parameters
- 401 — authorization error (invalid or missing API key)
- 403 — access denied (attempt to modify another user's task)
- 404 — resource not found
- 429 — rate limit of 30 requests per second exceeded
- 500 — server error; retry the request later