{"openapi":"3.1.0","info":{"title":"LinkJet Public API","version":"2026-05-13","description":"Create LinkJet projects, read project status, and connect external automations."},"servers":[{"url":"https://backlinkjet.ai/api/v1"}],"components":{"securitySchemes":{"LinkJetApiKey":{"type":"http","scheme":"bearer","bearerFormat":"LinkJet API key"}},"schemas":{"Project":{"type":"object","required":["id","name","primaryDomain","registeredDomain","createdAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"primaryDomain":{"type":"string"},"registeredDomain":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"ProjectCreateRequest":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"https://example.com"},"name":{"type":"string","example":"Example"}}},"ProjectCreateResponse":{"type":"object","required":["project","existing","links"],"properties":{"project":{"$ref":"#/components/schemas/Project"},"existing":{"type":"boolean"},"onboarding":{"type":"object","properties":{"scanRunId":{"type":["string","null"]},"crawlRunId":{"type":["string","null"],"deprecated":true,"description":"Compatibility alias for scanRunId."}}},"links":{"type":"object","properties":{"status":{"type":"string"},"dashboard":{"type":"string"}}}}},"ProjectListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}},"ProjectStatusResponse":{"type":"object","required":["project","setup","actions","site"],"properties":{"project":{"$ref":"#/components/schemas/Project"},"setup":{"type":"object","required":["state","summary","latestCrawl","pages"],"properties":{"state":{"type":"string","enum":["not_started","mapping","ready","needs_attention"]},"summary":{"type":"string"},"latestCrawl":{"type":["object","null"]},"pages":{"type":"object"}}},"actions":{"type":"object","required":["needsReview","summary","items"],"properties":{"needsReview":{"type":"boolean"},"summary":{"type":"string"},"items":{"type":"array","items":{"type":"object","required":["id","label","count","href"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer"},"href":{"type":"string"}}}}}},"site":{"type":"object","description":"Compatibility view of the latest crawl and page counts."},"queues":{"type":"object","deprecated":true,"description":"Deprecated compatibility alias for older clients."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}},"WebhookEvent":{"type":"object","required":["id","type","createdAt","workspaceId","projectId","data"],"properties":{"id":{"type":"string","example":"evt_lx0a1b2c_7f8g9h0i"},"type":{"type":"string","description":"Webhook event type. Current events are webhook.test and project.changed.","enum":["webhook.test","project.changed"]},"createdAt":{"type":"string","format":"date-time"},"workspaceId":{"type":"string"},"projectId":{"type":["string","null"]},"data":{"type":"object"}}},"ProjectChangedWebhookEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"const":"project.changed"},"data":{"oneOf":[{"type":"object","required":["action","project"],"properties":{"action":{"type":"string","enum":["created"],"example":"created"},"project":{"$ref":"#/components/schemas/Project"}}},{"type":"object","required":["method","path","status"],"properties":{"method":{"type":"string","example":"POST"},"path":{"type":"string","example":"/projects/:projectId/settings"},"status":{"type":"integer","example":200}}}]}}}]},"TestWebhookEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"const":"webhook.test"},"data":{"type":"object","required":["message","project"],"properties":{"message":{"type":"string","example":"This is a test delivery from LinkJet."},"project":{"$ref":"#/components/schemas/Project"}}}}}]}}},"paths":{"/projects":{"get":{"summary":"List projects","operationId":"listProjects","security":[{"LinkJetApiKey":["projects:read"]}],"responses":{"200":{"description":"Projects accessible to the API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectListResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a project","description":"Creates or reuses a project for a domain, then starts the first site scan.","operationId":"createProject","security":[{"LinkJetApiKey":["projects:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreateRequest"}}}},"responses":{"200":{"description":"Existing project returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreateResponse"}}}},"201":{"description":"Project created and first site scan started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreateResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Workspace plan does not allow this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key does not include projects:write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/projects/{projectId}/status":{"get":{"summary":"Get project status","operationId":"getProjectStatus","security":[{"LinkJetApiKey":["projects:read"]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project setup progress and next actions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectStatusResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Project not found for this API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{"project.changed":{"post":{"summary":"Receive a project update","operationId":"receiveProjectChangedWebhook","security":[],"parameters":[{"name":"LinkJet-Event","in":"header","required":true,"schema":{"type":"string","enum":["webhook.test","project.changed"]},"description":"The event type in the request body."},{"name":"LinkJet-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1760000000,v1=..."},"description":"HMAC-SHA256 signature over `{timestamp}.{rawBody}` using the webhook signing secret."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectChangedWebhookEvent"}}}},"responses":{"200":{"description":"Return any 2xx response to acknowledge delivery."}}}},"webhook.test":{"post":{"summary":"Receive a test delivery","operationId":"receiveTestWebhook","security":[],"parameters":[{"name":"LinkJet-Event","in":"header","required":true,"schema":{"type":"string","enum":["webhook.test","project.changed"]},"description":"The event type in the request body."},{"name":"LinkJet-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1760000000,v1=..."},"description":"HMAC-SHA256 signature over `{timestamp}.{rawBody}` using the webhook signing secret."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestWebhookEvent"}}}},"responses":{"200":{"description":"Return any 2xx response to acknowledge delivery."}}}}}}