Site files

Site files are the images, videos, and any other types of files used on articles. Please keep in mind that all files uploaded through this endpoint are public, even when the site is private.

Allowed file types:

jpg, jpeg, png, gif, pdf, zip, html, txt, gzip, svg, csv, sql, db, sqlite, doc, docx, docm, dot, md, css, xml, xhtml, gdoc, js, json

The file object

  • id integer

    The system-generated ID of the file

  • site_id integer

    The site id where the file belongs to.

  • filename string

    The name of the file.

  • size integer

    The size of the file in bytes.

  • url string

    The URL of the file.

  • created_at string

    The timestamp when the file was created.

  • updated_at string

    The timestamp when the file was last updated.

The file object

{
  "id": 1,
  "site_id": 1,
  "filename": "screenshot.jpeg",
  "size": 1024,
  "url": "https://www.yourdomain.com/storage/site-files/1/1/DF8ASD8A{...}.jpeg",
  "updated_at": "2019-06-01T18:47:16+00:00",
  "created_at": "2019-06-01T16:12:25+00:00"
}

Create a file

  • filename string optional

    The name of the file.

  • file file required

    The file to be uploaded.

Sample request

curl https://www.yourdomain.com/api/v1/sites/1/files \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -F "file=@/path/to/screenshot.jpeg" \ 
  -F filename="screenshot.jpeg"

Sample successful response

{
  "id": 1,
  "site_id": 1,
  "filename": "screenshot.jpeg",
  "size": 1024,
  "url": "https://www.yourdomain.com/storage/site-files/1/1/DF8ASD8A{...}.jpeg",
  "updated_at": "2019-06-01T18:47:16+00:00",
  "created_at": "2019-06-01T16:12:25+00:00"
}

Retrieve a file

Sample request

curl https://www.yourdomain.com/api/v1/sites/1/files/1 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

Sample successful response

{
  "id": 1,
  "site_id": 1,
  "filename": "screenshot.jpeg",
  "size": 1024,
  "url": "https://www.yourdomain.com/storage/site-files/1/1/DF8ASD8A{...}.jpeg",
  "updated_at": "2019-06-01T18:47:16+00:00",
  "created_at": "2019-06-01T16:12:25+00:00"
}

Update a file

  • filename string optional

    The name of the file.

Sample request

curl https://www.yourdomain.com/api/v1/sites/1/files/1 \
  --request PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d filename="Screenshot"

Sample successful response

{
  "id": 1,
  "site_id": 1,
  "filename": "Screenshot",
  "size": 1024,
  "url": "https://www.yourdomain.com/storage/site-files/1/1/DF8ASD8A{...}.jpeg",
  "updated_at": "2019-06-01T18:47:16+00:00",
  "created_at": "2019-06-01T16:12:25+00:00"
}

Delete a file

Sample request

curl https://www.yourdomain.com/api/v1/sites/1/files/1 \
  --request DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" 

If successful, the above request will return an empty response with 204 HTTP status code.

List all files

Sample request

curl https://www.yourdomain.com/api/v1/sites/1/files \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

Sample successful response

{
  "data": [
    {
      "id": 1,
      "site_id": 1,
      "filename": "Screenshot",
      "size": 1024,
      "url": "https://www.yourdomain.com/storage/site-files/1/1/DF8ASD8A{...}.jpeg",
      "updated_at": "2019-06-01T18:47:16+00:00",
      "created_at": "2019-06-01T16:12:25+00:00"
    },
    {...}
  ]
}