kunthawat/ALwrity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d889e83d6a86590de461ffee2a44df2bce2d538b
ALwrity/docs-site/docs/features/backlink-outreach/api-reference.md

450 lines
11 KiB
Markdown
Raw Blame History

# API Reference
Complete reference for all Backlink Outreach API endpoints. All endpoints require Clerk authentication via `Depends(get_current_user)`.
## Authentication
All endpoints use Clerk authentication. Include the session token in the `Authorization` header:
```
Authorization: Bearer <clerk_session_token>
```
The `user_id` is derived from the authenticated session — never from the request body.
## Endpoint Map
```mermaid
flowchart TD
subgraph Campaigns
C1[POST /campaigns]
C2[GET /campaigns]
C3[GET /campaigns/{id}]
C4[DELETE /campaigns/{id}]
end
subgraph Leads
L1[POST /campaigns/{id}/leads]
L2[POST /campaigns/{id}/leads/bulk]
L3[PATCH /campaigns/{id}/leads/{lead_id}/status]
L4[PATCH /campaigns/{id}/leads/bulk-status]
end
subgraph Discovery
D1[POST /discover/deep]
end
subgraph Email
E1[POST /emails/generate]
E2[POST /emails/personalize]
E3[POST /emails/subject-suggestions]
E4[POST /emails/follow-up]
E5[POST /emails/templates]
E6[GET /emails/templates]
E7[GET /emails/templates/{id}]
E8[DELETE /emails/templates/{id}]
end
subgraph Outreach
O1[POST /outreach/send]
O2[POST /policy/validate]
O3[GET /campaigns/{id}/attempts]
O4[GET /campaigns/{id}/follow-ups]
end
subgraph Replies
R1[POST /replies/poll]
R2[GET /campaigns/{id}/replies]
end
subgraph Suppression
S1[POST /suppression]
S2[GET /suppression]
end
subgraph Analytics
A1[GET /campaigns/{id}/analytics]
A2[GET /reporting/snapshot]
A3[GET /campaigns/{id}/export/leads]
A4[GET /campaigns/{id}/export/attempts]
A5[GET /campaigns/{id}/export/replies]
end
```
---
## Campaigns
### Create Campaign
`POST /api/v1/backlink-outreach/campaigns`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Campaign name. |
| `description` | string | No | Campaign description. |
| `keywords` | string[] | No | Target keywords for discovery. |
**Response:** `201 Created` — Campaign object.
### List Campaigns
`GET /api/v1/backlink-outreach/campaigns`
**Query Parameters:**
| Parameter | Type | Default | Description |
|---|---|---|---|
| `workspace_id` | string | user_id | Workspace to filter by. Defaults to authenticated user. |
**Response:** `200 OK` — Array of campaign objects.
### Get Campaign
`GET /api/v1/backlink-outreach/campaigns/{campaign_id}`
**Response:** `200 OK` — Campaign object with included leads.
### Delete Campaign
`DELETE /api/v1/backlink-outreach/campaigns/{campaign_id}`
**Response:** `204 No Content`
---
## Leads
### Add Lead
`POST /api/v1/backlink-outreach/campaigns/{campaign_id}/leads`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `website_url` | string | Yes | Target website URL. |
| `website_title` | string | No | Website title. |
| `contact_email` | string | No | Contact email address. |
| `quality_score` | float | No | Quality score (0-1). |
| `relevance_score` | float | No | Relevance score (0-1). |
| `guest_post_likelihood` | float | No | Guest post likelihood (0-1). |
| `source` | string | No | Source of the lead. |
**Response:** `201 Created` — Lead object.
### Bulk Add Leads
`POST /api/v1/backlink-outreach/campaigns/{campaign_id}/leads/bulk`
**Request Body:** Array of lead objects.
**Response:** `200 OK`
| Field | Type | Description |
|---|---|---|
| `added` | int | Number of leads successfully added. |
| `skipped` | int | Number of duplicates skipped. |
| `failed` | string[] | List of failed entries with reasons. |
### Update Lead Status
`PATCH /api/v1/backlink-outreach/campaigns/{campaign_id}/leads/{lead_id}/status`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | Yes | New status: discovered, contacted, replied, placed, bounced, lost. |
**Response:** `200 OK` — Updated lead object.
### Bulk Update Status
`PATCH /api/v1/backlink-outreach/campaigns/{campaign_id}/leads/bulk-status`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `lead_ids` | string[] | Yes | Lead IDs to update. |
| `status` | string | Yes | New status for all leads. |
**Response:** `200 OK`
| Field | Type | Description |
|---|---|---|
| `updated` | int | Number of leads successfully updated. |
| `failed` | string[] | List of lead IDs that failed to update. |
!!! warning "Partial failures"
Bulk operations may partially succeed. Always check the `failed` field and show appropriate warnings to users.
---
## Discovery
### Deep Discovery
`POST /api/v1/backlink-outreach/discover/deep`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `keyword` | string | Yes | Search keyword or phrase. |
| `campaign_id` | string | No | Campaign to save results to. |
| `max_results` | int | No | Maximum results to return (default 20). |
| `save_to_campaign` | bool | No | Auto-save results to campaign. |
**Response:** `200 OK`
| Field | Type | Description |
|---|---|---|
| `results` | array | Discovered opportunities with scores. |
| `saved_to_campaign` | int | Number of leads saved to campaign. |
| `save_failed` | int | Number of leads that failed to save. |
---
## Email
### Generate Email
`POST /api/v1/backlink-outreach/emails/generate`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `topic` | string | Yes | Email topic. |
| `tone` | string | No | professional, friendly, casual, formal. |
| `template_id` | string | No | Template to base generation on. |
**Response:** `200 OK` — `{ subject, body }`
### Personalize Email
`POST /api/v1/backlink-outreach/emails/personalize`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `base_email` | string | Yes | Email content to personalize. |
| `lead_name` | string | No | Lead's name. |
| `lead_website` | string | No | Lead's website. |
| `content_topic` | string | No | Topic to reference. |
**Response:** `200 OK` — `{ subject, body }`
### Subject Suggestions
`POST /api/v1/backlink-outreach/emails/subject-suggestions`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `topic` | string | Yes | Email topic. |
| `tone` | string | No | Tone for suggestions. |
**Response:** `200 OK` — `{ suggestions: string[] }`
### Generate Follow-up
`POST /api/v1/backlink-outreach/emails/follow-up`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `original_subject` | string | Yes | Subject of original email. |
| `original_body` | string | Yes | Body of original email. |
| `tone` | string | No | Tone for follow-up. |
**Response:** `200 OK` — `{ subject, body }`
### Create Template
`POST /api/v1/backlink-outreach/emails/templates`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Template name. |
| `subject` | string | Yes | Subject line with `{placeholders}`. |
| `body` | string | Yes | Email body with `{placeholders}`. |
| `category` | string | No | Template category. |
**Response:** `201 Created` — Template object.
### List Templates
`GET /api/v1/backlink-outreach/emails/templates`
**Response:** `200 OK` — Array of template objects.
### Get Template
`GET /api/v1/backlink-outreach/emails/templates/{template_id}`
**Response:** `200 OK` — Template object.
### Delete Template
`DELETE /api/v1/backlink-outreach/emails/templates/{template_id}`
**Response:** `204 No Content`
---
## Outreach
### Send Outreach
`POST /api/v1/backlink-outreach/outreach/send`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `campaign_id` | string | Yes | Campaign for the outreach. |
| `lead_id` | string | Yes | Lead to send to. |
| `subject` | string | Yes | Email subject. |
| `body` | string | Yes | Email body. |
| `workspace_id` | string | No | Workspace ID (default "default"). |
**Response:** `200 OK` — Outreach attempt object.
**Error responses:**
| Code | Meaning |
|---|---|
| `403` | Policy validation failed (caps, suppression, idempotency). |
| `500` | SMTP delivery failed (generic error, no stack trace). |
### Validate Policy
`POST /api/v1/backlink-outreach/policy/validate`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `recipient_email` | string | Yes | Recipient email address. |
| `sender_email` | string | Yes | Sender email address. |
| `subject` | string | No | Email subject for idempotency check. |
**Response:** `200 OK` — Policy validation result with `allowed`, `reason`, `legal_basis`, counts, and limits.
### List Attempts
`GET /api/v1/backlink-outreach/campaigns/{campaign_id}/attempts`
**Response:** `200 OK` — Array of outreach attempt objects.
### List Follow-ups
`GET /api/v1/backlink-outreach/campaigns/{campaign_id}/follow-ups`
**Response:** `200 OK` — Array of follow-up objects.
---
## Replies
### Poll Replies
`POST /api/v1/backlink-outreach/replies/poll`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `campaign_id` | string | No | Campaign to filter by. |
**Response:** `200 OK`
| Field | Type | Description |
|---|---|---|
| `replies_found` | int | Number of new replies processed. |
| `failed` | int | Number of replies that failed to process. |
### List Replies
`GET /api/v1/backlink-outreach/campaigns/{campaign_id}/replies`
**Response:** `200 OK` — Array of reply objects with classification.
---
## Suppression
### Add to Suppression
`POST /api/v1/backlink-outreach/suppression`
**Request Body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string | Yes | Email to suppress. |
| `reason` | string | No | Reason for suppression. |
**Response:** `201 Created` — Suppression record.
### List Suppressed
`GET /api/v1/backlink-outreach/suppression`
**Response:** `200 OK` — Array of suppression records.
---
## Analytics
### Campaign Analytics
`GET /api/v1/backlink-outreach/campaigns/{campaign_id}/analytics`
**Query Parameters:**
| Parameter | Type | Default | Description |
|---|---|---|---|
| `days` | int | 30 | Days to include in trends. |
**Response:** `200 OK` — Analytics object with leads_by_status, replies_by_classification, rates, and daily_send_volume.
### Reporting Snapshot
`GET /api/v1/backlink-outreach/reporting/snapshot`
**Response:** `200 OK` — Cross-campaign summary with total counts and rates.
### Export Leads
`GET /api/v1/backlink-outreach/campaigns/{campaign_id}/export/leads`
**Response:** `200 OK` — CSV file download.
### Export Attempts
`GET /api/v1/backlink-outreach/campaigns/{campaign_id}/export/attempts`
**Response:** `200 OK` — CSV file download.
### Export Replies
`GET /api/v1/backlink-outreach/campaigns/{campaign_id}/export/replies`
**Response:** `200 OK` — CSV file download.
---
## Common Error Responses
| Status | Meaning | Body |
|---|---|---|
| `401` | Not authenticated | `{"detail": "Not authenticated"}` |
| `403` | Policy blocked | `{"detail": "Policy validation failed", "reason": "..."}` |
| `404` | Not found | `{"detail": "Resource not found"}` |
| `422` | Validation error | `{"detail": [...validation errors]}` |
| `500` | Server error | `{"detail": "An internal error occurred"}` (generic, no stack trace) |
Reference in New Issue View Git Blame Copy Permalink