API reference

Every endpoint is GET and needs Authorization: Bearer <access_token>.

GET /api/v1/me

Who connected, and which companies you can read. Rely on this list rather than the one from connect time: a company drops off if the user loses access to it.

{
  "user": { "id": "u_123", "name": "Jane Doe", "email": "jane@acme.com" },
  "companies": [ { "id": "c_abc", "name": "Acme Coffee" } ]
}

GET /api/v1/companies/{companyId}/projects

{ "projects": [ { "id": "p_1", "name": "Spring Campaign", "status": "active" } ] }

GET /api/v1/companies/{companyId}/assets

Newest first, in pages.

Query	Description
`limit`	1–100, default 50
`cursor`	`nextCursor` from the previous page
`since`	Epoch milliseconds; only assets uploaded after this time
`assetType`	`videos`, `selects`, `social`, `photography`, `graphics`, `audio`, `documents`, `brand assets`
`projectId`	Only assets from one project

Use assetType or projectId in a request, not both.

{
  "assets": [
    {
      "id": "a_789",
      "name": "Spring Promo 30s",
      "mimeType": "video/mp4",
      "assetType": "social",
      "size": 48213377,
      "duration": 30.1,
      "width": 1080,
      "height": 1920,
      "projectId": "p_1",
      "projectName": "Spring Campaign",
      "tags": ["instagram"],
      "uploadDate": 1758650000000,
      "status": "ready",
      "hasTranscript": true,
      "thumbnailUrl": "https://…"
    }
  ],
  "nextCursor": "eyJ1Ijo…"
}

`status`	Meaning
`ready`	Can be downloaded.
`processing`	A video is still transcoding. Check `GET /assets/{id}` again until it’s `ready`.
`unavailable`	No file is attached to this asset.

thumbnailUrl is a signed link that expires after about an hour.

GET /api/v1/assets/{assetId}

The same fields as a list item, plus signed download links. The links expire at expiresAt (epoch seconds), so call this right before you download.

{
  "asset": {
    "id": "a_789",
    "…": "…",
    "download": {
      "url": "https://…/original?token=…&download=true&filename=Spring%20Promo%2030s.mp4",
      "mp4Url": "https://…/play_1080p.mp4?token=…",
      "filename": "Spring Promo 30s.mp4",
      "expiresAt": 1758657200
    }
  }
}

Send a Referer when downloading. Send Referer: https://app.vysual.com on every download. Links reject requests without it. For videos, url is the original upload; if it returns 404, download mp4Url (the best transcoded version) instead. mp4Url is null for anything that isn’t a video.

curl -L -H "Referer: https://app.vysual.com" -o "Spring Promo 30s.mp4" "$DOWNLOAD_URL"

GET /api/v1/assets/{assetId}/transcript

Available for video and audio assets with hasTranscript: true. Transcripts are generated a few minutes after upload. Pick the format with ?format=:

format=vtt (default): WebVTT captions, text/vtt
format=txt: plain text, text/plain
format=json: text, captions, and word timings

{
  "assetId": "a_789",
  "language": "en",
  "durationSec": 30.1,
  "text": "Spring is here and so is our new…",
  "vtt": "WEBVTT\n\n00:00:00.000 --> 00:00:02.400\nSpring is here…",
  "words": [ { "word": "Spring", "start": 0.12, "end": 0.48 } ]
}

words is null on older transcripts that have no word-level timing. A clip with no speech returns 200 {"assetId": "…", "noSpeech": true}. A 404 means there’s no transcript yet.