File Mutations

The File API provides a mutation for uploading files.

Upload File

Upload a file to the system. This is a two-step process:

1. Upload the file to the storage service
2. Create a file record in the system

Mutation Structure

mutation UploadFile(
  $url: String!
  $type: String!
  $filename: String
  $commentId: String
) {
  uploadFile(
    url: $url
    type: $type
    filename: $filename
    commentId: $commentId
  ) {
    id
    bytes
    cloudinaryId
    name
    url
    type
    version
    extension
    height
    width
  }
}

Input Fields

Field	Type	Description
url	String!	URL of the file to upload
type	String!	Type of upload ("profile-image" or "comment")
filename	String	Optional custom filename
commentId	String	Required when type is "comment"

Usage Examples

1. Upload Profile Image

mutation UploadProfileImage($url: String!) {
  uploadFile(
    url: $url
    type: "profile-image"
  ) {
    id
    url
    type
  }
}

2. Upload Comment Attachment

mutation UploadCommentFile(
  $url: String!
  $commentId: String!
) {
  uploadFile(
    url: $url
    type: "comment"
    commentId: $commentId
  ) {
    id
    name
    url
    type
  }
}

Error Handling

Authentication Errors

• Invalid API Key: Returned when the API key is missing or invalid
• Write Access Required: Returned when using a read-only API key
• SSO Type Required: Returned when ssoType header is missing
• SSO ID Required: Returned when ssoId header is missing
• Board ID Required: Returned when boardId header is missing (for profile images)

Validation Errors

• Invalid Type: Returned when the type is not "profile-image" or "comment"
• Comment ID Required: Returned when type is "comment" but commentId is not provided

Resource Errors

• Comment Not Found: Returned when the specified comment doesn't exist
• User Not Found: Returned when uploading a profile image for a non-existent user

Example Error Response

{
  "errors": [
    {
      "message": "Invalid type. Must be one of: profile-image, comment",
      "extensions": {
        "code": "INVALID_INPUT",
        "field": "type"
      }
    }
  ]
}