Post API: Uploading attachments

Context of this document: The Flip Post API for posts, comments, and attachments

Please find a specification for handling attachments with the link below.

Flip API Documentation - Post


To attach files to a post, they must first be uploaded using the attachment endpoint. Upon successful upload, you will receive an attachment ID for further use.

Please note and keep in mind:

  • The file size is limited to 1 GB per file.
  • The Content-Transfer-Encoding: base64 is not supported.
  • All Flip APIs only allow attaching a file using the attachment_id when background processing has completed with the status FINISHED. This means checking the status after upload and before further usage is mandatory.

Uploading files

To upload a file, send a multipart/form-data POST request to /api/external/v1/attachments.

Here is an example using curl.


curl -H "authorization: Bearer $TOKEN" -F file=@$PATH_TO_FILE <https://$DOMAIN/api/external/v1/attachments>

Replace $PATH_TO_FILE with the location of the file you want to upload. Don't forget to add a Content-Type header with the file type to the part, if you build multipart/form-data manually (see This determines how the attachment is displayed in the application.

On success, you get a 202 HTTP status code. The 202 status code indicates that the file is still being processed in the background. Background processing of a file is necessary to provide the users of the Flip-App the best possible experience.


	"attachment_id": "4c76e620-6daa-46e6-9da1-9ac96abab601"

Now, the attachment_id can be used for two things:

  1. Checking the status of the background processing.
  2. Attaching the file to content using another API like the Post-API.

Check the background processing status

To get the status of your file in progress, send a GET request to /api/external/v1/attachments/$ATTACHMENT_ID/status.

Here is an example using curl.


curl -H "authorization: Bearer $AUTH" \\

Replace $ATTACHMENT_ID with the attachment_id retrieved in the previous step.


	"attachment_id": "4c76e620-6daa-46e6-9da1-9ac96abab601",
	"type": "VIDEO",
	"status": "IN_PROGRESS"

The fields explained:

  • attachment_id: the ID of the file you requested a status for
  • type: the file type we detected, either VIDEO, IMAGE or MISC. MISC is all kinds of files like text documents, PDFs, archives…
  • status: the status of the background processing, possible values are:
    • IN_PROGRESS: Attachment is still being processed.
    • FINISHED: The processing has finished successfully, and the attachment can now be used elsewhere.
    • FAILED_BAD_FILE: The uploaded file is corrupt and cannot be processed.
    • FAILED_INTERNAL_ERROR: We encountered an internal error while processing the attachment. Try again and if the problem persists, notify your Flip contact person.

When the status is FINISHED, the attachment_id can be used in other Flip APIs.

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request



Please sign in to leave a comment.