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.

Request:

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 https://en.wikipedia.org/wiki/MIME#Multipart_messages). 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.

Response:

{
	"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.

Request:

curl -H "authorization: Bearer $AUTH" \\
	<https://$DOMAIN/api/external/v1/attachments/$ATTACHMENT_ID/status>

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

Response:

{
	"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.