Skip to main content

API Contracts Documentation

This document describes the API endpoints used by the frontend and E2E tests. It serves as a contract reference to ensure tests match actual API behavior.

Models​

List Models​

GET /models
GET /models?packId={id}
GET /models?projectId={id}

Response:

[
  {
    "id": 1,
    "name": "test-cube",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z",
    "activeVersionId": 1,
    "thumbnailUrl": "/models/1/thumbnail/file?t=..."
  }
]

Get Model Details​

GET /models/{id}

Response: Returns model details WITHOUT versions array. Use version-specific endpoints for version data.

{
  "id": 1,
  "name": "test-cube",
  "activeVersionId": 1,
  "files": [...],
  "packs": [...],
  "projects": [...],
  "textureSets": [...]
}

Note: No versions property exists in this response.

Upload Model (Create)​

POST /models
Content-Type: multipart/form-data

Form fields:

  • file: Model file (.glb, .fbx, etc.)

Upload New Version​

POST /models/{id}/versions?setAsActive=false
Content-Type: multipart/form-data

Form fields:

  • file: Model file

Required query param: setAsActive=false or setAsActive=true

Set Active Version​

POST /models/{id}/active-version/{versionId}

Delete Model (Soft)​

DELETE /models/{id}

Delete Version (Soft)​

DELETE /models/{modelId}/versions/{versionId}

Sprites​

List Sprites​

GET /sprites

Get Sprite​

GET /sprites/{id}

Create Sprite​

POST /sprites
Content-Type: multipart/form-data

Form fields:

  • file: Image file
  • name: Sprite name
  • spriteType: 1 (static), 2 (sprite sheet), 3 (GIF), 4 (APNG), 5 (WebP)
  • categoryId (optional): Category to assign

Update Sprite​

PUT /sprites/{id}
Content-Type: application/json

Body:

{
  "name": "new-name",
  "categoryId": 1
}

Note: Uses PUT, not PATCH.

Delete Sprite (Soft)​

DELETE /sprites/{id}

Sprite Categories​

List Categories​

GET /sprite-categories

Response:

{
  "categories": [
    { "id": 1, "name": "Test Category", "description": "..." }
  ]
}

Create Category​

POST /sprite-categories
Content-Type: application/json

Body:

{
  "name": "Category Name",
  "description": "Optional description"
}

Update Category​

PUT /sprite-categories/{id}

Delete Category​

DELETE /sprite-categories/{id}

Packs​

List Packs​

GET /packs

Get Pack​

GET /packs/{id}

Create Pack​

POST /packs
Content-Type: application/json

Body:

{
  "name": "Pack Name",
  "description": "Optional"
}

Add Model to Pack​

POST /packs/{packId}/models/{modelId}

Remove Model from Pack​

DELETE /packs/{packId}/models/{modelId}

Projects​

List Projects​

GET /projects

Create Project​

POST /projects
Content-Type: application/json

Body:

{
  "name": "Project Name",
  "description": "Optional"
}

Add Model to Project​

POST /projects/{projectId}/models/{modelId}

Remove Model from Project​

DELETE /projects/{projectId}/models/{modelId}

Texture Sets​

List Texture Sets​

GET /texture-sets

Create Texture Set​

POST /texture-sets
Content-Type: multipart/form-data

Associate with Model Version​

POST /texture-sets/{packId}/model-versions/{modelVersionId}

Thumbnails​

Get Model Thumbnail​

GET /models/{id}/thumbnail/file

Regenerate Thumbnail​

POST /thumbnails/regenerate/{modelId}

Upload Custom Thumbnail​

POST /thumbnails/custom/{modelId}
Content-Type: multipart/form-data

Form fields:

  • file: Image file (PNG, JPG, WebP)

Common Patterns​

Error Response​

{
  "error": "ErrorCode",
  "message": "Human-readable message"
}

Soft Delete Pattern​

All delete endpoints perform soft deletes. Items move to recycle bin and can be restored.

File URLs​

File downloads use the pattern: /files/{fileId}/download