API v1

VideoForge API.

Programmatically submit videos to the uniquification pipeline, fetch reports, and manage your jobs. REST + Model Context Protocol.

Quickstart

Three steps. Get a token, submit a job, fetch the result.

1. Mint a token in Settings → API tokens.
2. Call POST /api/v1/jobs with a source URL.
3. Poll GET /api/v1/jobs/{id} or set up an Agency webhook.

curl -X POST https://your-app.lovable.app/api/v1/jobs \
  -H "Authorization: Bearer vf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"source_url":"https://example.com/in.mp4","intensity":"standard"}'

Authentication

All API calls require a Bearer token. Tokens look like vf_live_… and are scoped to a single user.

Authorization: Bearer vf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens are hashed at rest. We never store the plaintext. If a token is lost, revoke it and mint a new one.

Endpoints

GET/api/v1/health

Health check

Returns API status and version. Unauthenticated.

Response

{
  "status": "ok",
  "version": "1.0.0",
  "ts": "2026-06-08T05:00:00.000Z"
}

GET/api/v1/usage

Current usage vs plan limits

Returns this billing period's job count, monthly cap, concurrent-job cap, and plan tier.

Response

{
  "plan": "marketer",
  "monthly_cap": 150,
  "monthly_used": 42,
  "concurrent_cap": 3
}

POST/api/v1/jobs

Create a new uniquification job

Submit a video for processing. The source must already be uploaded to a publicly reachable URL (S3, R2, Lovable Storage signed URL).

Request body

source_urlrequiredstring (URL)

Direct URL to the source video.

intensity'subtle' | 'standard' | 'aggressive'

Pipeline intensity preset. Defaults to 'standard'.

Response

{
  "id": "9f5d-...-job-id",
  "status": "queued",
  "created_at": "2026-06-08T05:00:00.000Z"
}

GET/api/v1/jobs

List your jobs

Paginated list of jobs owned by the authenticated user.

Query params

limitinteger (1-100)

Page size. Defaults to 25.

statusstring

Filter by status: queued, processing, complete, failed.

Response

{
  "jobs": [
    { "id": "...", "status": "complete", "verdict": "STRONG", ... }
  ],
  "next_cursor": null
}

GET/api/v1/jobs/{id}

Get a single job

Returns full job details including the uniqueness report.

Response

{
  "id": "...",
  "status": "complete",
  "report": { "verdict": "STRONG", "pHash": {...}, "audio": {...} },
  "output_url": "https://...signed-url"
}

DELETE/api/v1/jobs/{id}

Delete a job

Permanently deletes the job and all associated source/output files.

Response

{ "ok": true }

MCP — Model Context Protocol

Model Context Protocol endpoint. Authenticate with the same Bearer token used for the REST API. Supports tools: submit_video, get_job, list_jobs, get_usage.

claude_desktop_config.json

{
  "mcpServers": {
    "videoforge": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-app.lovable.app/api/public/mcp"],
      "env": { "AUTH_TOKEN": "vf_live_..." }
    }
  }
}

Errors

Errors return a JSON envelope:

{
  "error": {
    "code": 401,
    "message": "Invalid token"
  }
}

Status	Meaning
401	Missing / invalid / revoked token
402	Plan upgrade required, or monthly cap reached
404	Resource not found
422	Validation error (bad input)
429	Concurrency cap reached — retry later