File Uploading

Space works as permanent storage for all uploaded files. After an application uploads a file to Space, it receives an attachment ID. It can then use this ID to attach the file or add a file link, e.g., to issues or messages. Space supports all basic file formats like image, video, text, and binary files.

Upload files

To upload a file to Space, the application must send a POST request to the following endpoint: /uploads?name=<filename>&spaceMediaType=<spaceMediaType>

filename – (Required) the name of the file to upload.
spaceMediaType – (Optional) the usage context for the uploaded file. If specified, Space will generate a file preview appropriate for the intended context, such as a chat message or an issue. If not (or if the specified context does not match the actual context where the file is used), the file will be shown as is without a preview. Possible values:
- issue-image-attachment – the file is an image attached to an issue.
- chat-image-attachment – the file is an image attached to a chat message.
- chat-video-attachment – the file is a vide attached to a chat message.
The Content-Type HTTP header is required.
The file must be sent in the request body.
The bearer token authorization is required. Permissions are not checked, so any authorized client can upload files to Space. Learn how to get a token
In the response, the application receives a string with the attachment ID. Learn how you can use this ID to reference the uploaded files

There's no specific method for uploading files in the Kotlin Space SDK. Instead, you can use the ktorClient that is built into the SpaceClient class to send a POST request to the upload endpoint.

val baseClient = HttpClient().config { configureKtorClientForSpace() }
// a Space client with the Client Credentials flow authorization
val spaceClient = SpaceClient(
    baseClient, SpaceAppInstance(clientId, clientSecret, spaceUrl),
    SpaceAuth.ClientCredentials(PermissionScope.fromString("**"))
)

// upload a file to Space, return the attachment ID
suspend fun uploadFileWithSpaceClient(
    url: String, fileBytes: ByteArray,
    fileName: String, spaceMediaType: String
): String {
    // get token from the authorized client
    val token = spaceClient.auth.token(spaceClient.ktorClient, spaceClient.appInstance).accessToken
    // generate the upload URL
    val uploadUrl = "$url/uploads?name=$fileName&spaceMediaType=$spaceMediaType"

    // use the ktorClient to send a POST request to the upload URL
    val uploadSpaceAttachmentResponse = spaceClient.ktorClient.request(uploadUrl) {
        method = HttpMethod.Post
        setBody(ByteArrayContent(fileBytes))
        header(HttpHeaders.ContentType, getContentType(fileName))
        header(HttpHeaders.Authorization, "Bearer $token")
    }
    // return the attachment ID
    return uploadSpaceAttachmentResponse.body<String>()
}

POST https://mycompany.jetbrains.space/uploads?name=myphoto.jpg&spaceMediaType=chat-image-attachment
Authorization: Bearer access_token_goes_here
Content-Type: image/jpeg

file_byte_array_data_goes_here

Reference uploaded files

Once your application has the file's attachment ID, it can reference the file in Space.

Attachment to a message

When sending a message, add the file as an attachment by specifying its ID in the attachments field. Note that in Space you can send messages not only to chat channels or team members, but also to issues, documents, code reviews, and other modules that support commenting.

spaceClient.chats.messages.sendMessage(
    channel = ChannelIdentifier.Review(ReviewIdentifier.Id("here_goes_review_id")),
    content = ChatMessage.Text(text = "Take a look at this image"),
    attachments = listOf(ImageAttachment(
        id = "here_goes_attachment_id",
        width = 100,
        height = 100
    ))
)

POST https://mycompany.jetbrains.space/api/http/chats/messages/send-message
Authorization: Bearer here_goes_access_token
Accept: application/json
Content-Type: application/json

{
    "channel": "codeReview:id:here_goes_review_id",
    "content": {
        "className": "ChatMessage.Text",
        "text": "Take a look at this image"
    },
    "attachments": [
        {
            "className": "ImageAttachment",
            "id": "here_goes_attachment_id",
            "width": 100,
            "height": 100
        }
    ]
}

All message attachments are private by default. They are available only to the users within the current scope, for example, to the members of the current chat channel. To make an attachment public, use the getPublicUrl API method.

spaceClient.uploads.chat.publicUrl.getPublicUrl(
    channel = ChannelIdentifier.Review(ReviewIdentifier.Id("here_goes_review_id")),
    message = ChatMessageIdentifier.InternalId("here_goes_message_id"),
    attachmentId = "here_goes_attachment_id"
)

GET https://mycompany.jetbrains.space/api/http/uploads/chat/public-url/codeReview:id:here_goes_review_id/id:here_goes_message_id/here_goes_attachment_id
Authorization: Bearer here_goes_access_token
Accept: application/json

Attachment to an issue

When creating an issue, add the file as an attachment by specifying its ID in the attachments field:

spaceClient.projects.planning.issues.createIssue(
    project = ProjectIdentifier.Key("MY-PROJECT"),
    title = "My Issue",
    status = "Open",
    attachments = listOf(ImageAttachment(
        id = "here_goes_attachment_id",
        width = 100,
        height = 100
    ))
)

POST https://mycompany.jetbrains.space/api/http/projects/key:MY-PROJECT/planning/issues
Authorization: Bearer here_goes_access_token
Accept: application/json
Content-Type: application/json

{
    "title": "My Issue",
    "status": "Open",
    "attachments": [
        {
            "className": "ImageAttachment",
            "id": "here_goes_attachment_id",
            "width": 100,
            "height": 100
        }
    ]
}

You can also add attachments to existing issues:

spaceClient.projects.planning.issues.attachments.addAttachments(
    project = ProjectIdentifier.Key("MY-PROJECT"),
    issueId = IssueIdentifier.Key("MY-PROJECT-T-39"),
    attachments = listOf(FileAttachment(
        id = "here_goes_attachment_id",
        sizeBytes = 1024,
        filename = "myfile.txt",
    ))
)

POST https://mycompany.jetbrains.space/api/http/projects/key:MY-PROJECT/planning/issues/key:MY-PROJECT-T-39/attachments
Authorization: Bearer here_goes_access_token
Accept: application/json
Content-Type: application/json

{
    "attachments": [
        {
             "className": "FileAttachment",
             "id": "here_goes_attachment_id",
             "sizeBytes": 1024,
             "filename": "myfile.txt"
        }
    ]
}

File link

In all places in Space that support Markdown, you can insert a link to a file by specifying its ID. For example: ![image](/d/here_goes_attachment_id) or [download the file]/d/here_goes_attachment_id

If the attachment is public, you can share a link to it with anyone: https://mycompany.jetbrains.space/d/here_goes_attachment_id

Last modified: 09 August 2023