File Management API

Overview

The API supports file-based push. For push methods, see File push.

This module covers file upload, query, and delete.

You must upload a file via this module and obtain a file_id before using file push.

API host

https://api.jpush.cn/v3/files

Authentication

• See Authentication in the REST API overview.

• Since 2020.08.11, base64(dev_key:dev_secret) is supported. This requires VIP file group push permission on the Jiguang platform. Only authorized developers can call file APIs with dev_key; otherwise error 1105 is returned.

• dev_key and dev_secret are the "Developer ID (DevKey)" and "API DevSecret" in your Jiguang account.

Upload file

Write alias or registration_id values to a local file, upload to Jiguang servers, then push by file reference.

Endpoint

POST https://api.jpush.cn/v3/files/{type}

Request example

          curl -F "filename=@registration_id.txt" -F "ttl=720" https://api.jpush.cn/v3/files/registration_id -u "115cc609860982ede0e3bdd4:2e2023ade697b989087dcc53"

> POST /v3/files/registration_id HTTP/2
> Host: api.jpush.cn
> Authorization: Basic MTE1Y2M2MDk4NjA5ODJlZGUwZTNiZGQ0OjJlMjAyM2FkZTY5N2I5ODkwODdkY2M1Mw==
> User-Agent: curl/7.64.1
> Accept: */*
> Content-Length: 209
> Content-Type: multipart/form-data; boundary=------------------------6fd6ff237027ae34

        

Request parameters

• type File type: alias or registration_id (required).
• filename File name
• One registration_id or alias per line; leading/trailing spaces and newlines are trimmed.
• txt format only; UTF-8 encoding required.
• Max 10 MB.
• Without ttl, files are kept 720 hours (30 days) by default, then deleted.
• Max 20 valid files per app.
• ttl File lifetime
• Optional integer, hours; default 720.
• Range [1, 720] (1 hour to 30 days).

Response example

          HTTP/1.1 200

{
"file_id": "8103a4c628a0b98994ec1949-374004a2-bc6c-4abc-bde5-9f1a9671d307"
}

        

Response parameters

• file_id: File ID for delete, query, and push.

List valid files

Get the list of valid files stored on JPush servers.

Endpoint

GET https://api.jpush.cn/v3/files

Request example

          curl -X GET -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" https://api.jpush.cn/v3/files

        

Response example

          HTTP/1.1 200

{
 "total_count": 3,
 "files": [
 {"file_id": "xxxx-xxxx", "type": "alias", "create_time": "2019-10-12 13:36:55", "expire_time": "2019-10-19 13:36:57", "file_name": "xxx"},
 {"file_id": "xxxx-xxxx", "type": "registration_id", "create_time": "2019-10-13 13:36:55", "expire_time": "2019-10-20 13:36:57", "file_name": "xxx"},
 {...}
 ]
}

        

Response parameters

JSON Array

• total_count: Number of valid files.
• files File list
• file_id File ID
• type alias or registration_id
• create_time Upload time
• expire_time Expiration time (when ttl was set)
• file_name Upload file name (since 2021-10-14)

Delete file

Delete a specified file on JPush servers.

Endpoint

DELETE https://api.jpush.cn/v3/files/{file_id}

Request example

          curl -X DELETE -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" https://api.jpush.cn/v3/files/7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307

        

Response example

          HTTP/1.1 200

        

Response parameters

N/A

• Success returns empty body with HTTP 200.
• Non-existent file_id is treated as success.
• For immediate push, delete the file at least 5 minutes after creating the push task, or the push may fail.
• For scheduled file push, deleting the file before execution causes push failure.

Get file details

Query details of a specified file on JPush servers.

Endpoint

GET https://api.jpush.cn/v3/files/{file_id}

Request example

          curl -XGET -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" https://api.jpush.cn/v3/files/7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307

        

Response example

          HTTP/1.1 200

{
 "file_id": "7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307",
 "type": "alias", // 文件类型
 "create_time": "2019-10-12 13:36:55", // 创建时间
 "expire_time": "2019-10-20 13:36:57", // 文件过期时间，当设置了文件有效期（即提交了ttl参数）则会携带该字段返回
 "file_name": "test.txt" // 文件上传时的文件名（自2021-10-14日启用）
}

        

Response parameters

JSON Object

• file_id File ID
• type alias or registration_id
• create_time Upload time
• expire_time Expiration time (when ttl was set)
• file_name Upload file name (since 2021-10-14)

API responses

Rate limits

• Max 20 valid (non-expired) files; exceeding returns failure.
• Max file size 10 MB
• Max retention 30 days
• API rate limit 20 requests/min
• All file API calls share the same rate pool.