# Links
Link Engine for internal linking
## List Link Engine sites
> Returns sites with Link Engine configuration. Requires Power plan or higher.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"LinkEngineSite":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"link_engine_status":{"type":"string","enum":["active","paused","indexing","inactive","error"]},"link_engine_url_count":{"type":"integer"},"link_engine_last_indexed_at":{"type":"string","format":"date-time","nullable":true},"link_engine_error":{"type":"string","nullable":true},"category_id":{"type":"string","format":"uuid","nullable":true},"category_name":{"type":"string","nullable":true},"has_link_config":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/links":{"get":{"summary":"List Link Engine sites","description":"Returns sites with Link Engine configuration. Requires Power plan or higher.","parameters":[{"in":"query","name":"page","schema":{"type":"integer"}},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search by domain"},{"in":"query","name":"category","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"status","schema":{"type":"string","enum":["all","active","paused","indexing","inactive","error"]}}],"responses":{"200":{"description":"List of Link Engine sites","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LinkEngineSite"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}}},"tags":["Links"]}}}}
```
## GET /v1/links/stats
> Get Link Engine statistics
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"LinkEngineStats":{"type":"object","properties":{"total_sites":{"type":"integer"},"active_sites":{"type":"integer"},"paused_sites":{"type":"integer"},"indexing_sites":{"type":"integer"},"error_sites":{"type":"integer"},"total_urls":{"type":"integer"}}}}},"paths":{"/v1/links/stats":{"get":{"summary":"Get Link Engine statistics","responses":{"200":{"description":"Link Engine stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkEngineStats"}}}}},"tags":["Links"]}}}}
```
## GET /v1/links/categories
> List link categories
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"LinkCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"color":{"type":"string"},"site_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/links/categories":{"get":{"summary":"List link categories","responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LinkCategory"}}}}}},"tags":["Links"]}}}}
```
## POST /v1/links/categories
> Create a link category
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"LinkCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"color":{"type":"string"},"site_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/links/categories":{"post":{"summary":"Create a link category","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":50},"description":{"type":"string","maxLength":200},"color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#6366f1"}}}}}},"responses":{"201":{"description":"Category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkCategory"}}}}},"tags":["Links"]}}}}
```
## Get link injection status
> Poll the status of a link injection job.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/links/inject":{"get":{"summary":"Get link injection status","description":"Poll the status of a link injection job.","parameters":[{"in":"query","name":"request_id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Request ID from POST /v1/links/inject"},{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"Page for per-article status"}],"responses":{"200":{"description":"Link injection job status","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"status":{"type":"string","enum":["waiting","progress","complete","failed","canceled"]},"total_articles":{"type":"integer"},"completed_articles":{"type":"integer"},"failed_articles":{"type":"integer"},"total_links_added":{"type":"integer"},"articles":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string"},"linksAdded":{"type":"integer"},"error":{"type":"string"}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}},"404":{"description":"Job not found"}},"tags":["Links"]}}}}
```
## Run Link Engine on articles
> Inject internal and/or external links into a batch of completed articles.\
> Returns a request\_id for polling status via GET. Up to 500 articles per call.\
> Articles must belong to the authenticated team and have status "complete".
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Links","description":"Link Engine for internal linking"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/links/inject":{"post":{"summary":"Run Link Engine on articles","description":"Inject internal and/or external links into a batch of completed articles.\nReturns a request_id for polling status via GET. Up to 500 articles per call.\nArticles must belong to the authenticated team and have status \"complete\".\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["article_ids","site_id"],"properties":{"article_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500,"description":"Article IDs to inject links into"},"site_id":{"type":"string","format":"uuid","description":"Site ID (must have Link Engine configured)"},"max_links_per_article":{"type":"integer","minimum":1,"maximum":20,"default":5,"description":"Maximum links to inject per article"},"include_internal":{"type":"boolean","default":true,"description":"Include internal links"},"include_external":{"type":"boolean","default":true,"description":"Include external links"}}}}}},"responses":{"200":{"description":"Link injection job created","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"total_articles":{"type":"integer"},"status":{"type":"string","enum":["waiting"]}}}}}},"400":{"description":"Invalid request or Link Engine not configured"},"403":{"description":"Plan does not support Link Engine"}},"tags":["Links"]}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://learn.cuppa.ai/rest-api/links.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.