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.
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
Once your application has the file's attachment ID, it can reference the file in Space.
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
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"
}
]
}
In all places in Space that support Markdown, you can insert a link to a file by specifying its ID. For example: 
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
Thanks for your feedback!