Files API

API endpoints for managing files in Moqup projects.

The Files API allows you to manage design files programmatically. Files are referenced by URL - you must first upload the file to your own storage or Moqup's storage, then create a file record with the URL.

Endpoints

Method	Endpoint	Description
GET	`/projects/{id}/files`	List project files
POST	`/projects/{id}/files`	Create file
GET	`/files/{id}`	Get file details
PATCH	`/files/{id}`	Update file
DELETE	`/files/{id}`	Delete file

List Files

Request

bash

GET /v1/projects/{project_id}/files
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter: `draft`, `review`, `approved`, `rejected`
`type`	string	Filter: `image`, `video`, `pdf`

Response

json

{
  "data": [
    {
      "id": "abc123-def456",
      "project_id": "proj_xyz",
      "title": "Homepage Hero",
      "type": "image",
      "url": "https://storage.example.com/hero.png",
      "thumbnail_url": "https://storage.example.com/hero-thumb.png",
      "status": "review",
      "size": 2458624,
      "created_at": "2025-01-08T10:00:00Z",
      "updated_at": "2025-01-10T14:30:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "perPage": 20,
    "hasMore": false
  }
}

Create File

Create a file record by providing a URL to the file. The file must already be uploaded to a publicly accessible location.

Request

bash

POST /v1/projects/{project_id}/files
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "title": "Homepage Design",
  "type": "image",
  "url": "https://storage.example.com/design.png",
  "thumbnail_url": "https://storage.example.com/design-thumb.png",
  "status": "draft",
  "size": 1548792
}

Parameters

Field	Type	Required	Description
`title`	string	Yes	File title
`type`	string	Yes	File type: `image`, `video`, or `pdf`
`url`	string	Yes	URL to the file
`thumbnail_url`	string	No	URL to thumbnail
`status`	string	No	Status: `draft` (default), `review`, `approved`, `rejected`
`size`	integer	No	File size in bytes
`duration`	integer	No	Duration in seconds (for videos)
`page_count`	integer	No	Number of pages (for PDFs)

Response

json

{
  "data": {
    "id": "abc123-def456",
    "project_id": "proj_xyz",
    "title": "Homepage Design",
    "type": "image",
    "url": "https://storage.example.com/design.png",
    "thumbnail_url": "https://storage.example.com/design-thumb.png",
    "status": "draft",
    "size": 1548792,
    "created_at": "2025-01-10T15:00:00Z",
    "updated_at": "2025-01-10T15:00:00Z"
  }
}

Get File

Request

bash

GET /v1/files/{id}
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "data": {
    "id": "abc123-def456",
    "project_id": "proj_xyz",
    "title": "Homepage Hero",
    "type": "image",
    "url": "https://storage.example.com/hero.png",
    "thumbnail_url": "https://storage.example.com/hero-thumb.png",
    "status": "review",
    "size": 2458624,
    "project": {
      "id": "proj_xyz",
      "name": "Website Redesign",
      "workspace_id": "ws_123"
    },
    "versions": [
      {
        "id": "ver_1",
        "version_number": 1,
        "url": "https://storage.example.com/hero-v1.png",
        "created_at": "2025-01-08T10:00:00Z"
      }
    ],
    "created_at": "2025-01-08T10:00:00Z",
    "updated_at": "2025-01-10T14:30:00Z"
  }
}

The response includes the associated project and file versions.

Update File

Request

bash

PATCH /v1/files/{id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "title": "Homepage Hero - Final",
  "status": "approved"
}

Parameters

Field	Type	Description
`title`	string	Update file title
`status`	string	`draft`, `review`, `approved`, `rejected`
`url`	string	Update file URL
`thumbnail_url`	string	Update thumbnail URL

Response

json

{
  "data": {
    "id": "abc123-def456",
    "title": "Homepage Hero - Final",
    "status": "approved",
    "updated_at": "2025-01-10T16:00:00Z"
  }
}

Delete File

Requires write permission.

Request

bash

DELETE /v1/files/{id}
Authorization: Bearer YOUR_API_KEY

Response

Returns 204 No Content on success.

File Status

Files have a status field that tracks the review state:

Status	Description
`draft`	Initial state, not ready for review
`review`	Ready for client review
`approved`	Approved by client
`rejected`	Rejected, needs revision

Errors

Code	Description
400	Invalid parameters (missing title, type, or url)
401	Authentication required
403	Insufficient permissions
404	File or project not found

Error Response

json

{
  "error": {
    "message": "title is required",
    "code": 400
  }
}

Examples

Create Image File

bash

POST /v1/projects/proj_123/files
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "title": "Landing Page Design",
  "type": "image",
  "url": "https://cdn.example.com/landing.png",
  "thumbnail_url": "https://cdn.example.com/landing-thumb.png"
}

Create Video File

bash

POST /v1/projects/proj_123/files
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "title": "Product Demo",
  "type": "video",
  "url": "https://cdn.example.com/demo.mp4",
  "thumbnail_url": "https://cdn.example.com/demo-thumb.jpg",
  "duration": 120
}

Create PDF File

bash

POST /v1/projects/proj_123/files
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "title": "Brand Guidelines",
  "type": "pdf",
  "url": "https://cdn.example.com/brand.pdf",
  "page_count": 24
}

Update Status to Approved

bash

PATCH /v1/files/file_123
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "status": "approved"
}

Filter by Status

bash

GET /v1/projects/proj_123/files?status=review
Authorization: Bearer YOUR_API_KEY

Next Steps

Annotations API - Manage feedback on files
Rate Limits - Understand usage limits