--- title: Export a PDF document from an iWork file framework: iWork Document Exporting API role: symbol role_heading: Web Endpoint platforms: [iwork 14.0+] path: iworkdocumentexportingapi/create-an-export-job-(v2) --- # Export a PDF document from an iWork file Create a PDF preview of an iWork document using JSON Web Token (JWT) authorization. ## URL POST https://iworkpreviewapi.icloud.com/iwork/api/v2/export ## Header Parameters Content-Length: The number of bytes in the request body as defined in RFC 7230. The service doesn’t support chunked transfer coding. authorization: A JWT as defined in the Authentication and as defined in the Authentication and request payload section, below. ## Response Codes 200 OK: Successful export. If the service successfully processed the request and exported the document, the server returns an HTTP 200 response with the exported file in the body. 400 Bad Request: Invalid request. If the request is invalid for some reason (such as missing or invalid header values), the server returns an HTTP 400 response. The server returns the reason for the error in the response body, for example: Invalid filename. 403 Forbidden: Authentication failure. If the server can’t validate the signature, either because the signature is invalid, or because the key pair can’t recognize the signature, the server returns an HTTP 403 response with body Invalid signature. If the document is password-protected, the server responds with a HTTP 403 response with body Password protected document. 404 Not Found: 411 Length Required: 413 Request Entity Too Large: Request too large. The server returns this error if the document is over 1 GB. 429 : Client is sending too many requests. If you’re sending too many requests, the server returns an HTTP 429 response. The server may give this response without completely reading the contents of the request. In this case, don’t retry the request. 500 Internal Server Error: For other errors, the server returns an HTTP 500 response. For export errors caused by a corrupted document or other irrecoverable errors, the response body contains Irrecoverable export error. In this case, don’t retry exporting the same document. In general, don’t retry unless there is a Retry-After header in the response. 503 Service Unavailable: Server asks client to retry. In some situations where the server is under heavy load, the server may return an HTTP 503 response. The Retry-After response header specifies the number of seconds after which you may retry. Don’t retry unless there is a Retry-After header. The server may give this response without completely reading the contents of the request. ## Privacy Notice Privacy Notice It’s important for apps to inform people that uploaded iWork documents are temporarily stored on Apple servers for the purpose of conversion. Provide people the option to enable and disable the iWork preview feature, and display a privacy notice when doing so, such as “When using iWork online previews, your files will be temporarily stored on Apple servers.” Supported files The maximum file size the service supports is 1 GB and the service can only convert documents not protected with a password. Authentication and request payload For each request, the iWork service requires a signature so that the service can confirm that the client has permission to access the API. The service uses a JSON Web Token (JWT) to transfer the signature, information about the client and the details of the document export request. Sign the JWT with an ES256 key acquired from Apple Developer Keys. Using Open Source libraries recommended by JWT.io may simplify the process of constructing and signing JWTs. Include these claims in the JWT header: | | | Include these claims in the JWT payload: | | | | | | Put the signed JWT as-is in the HTTP authorization header. Clients need to ensure that their system clocks are accurate: The service rejects the signed JWT if the current time falls outside of the time window specified by iat and exp. Reconstruct and sign the JWT with a new DateTime for each request even if you’re retrying the request. The method to authenticate and sign the requests may change in light of new developments in the security field. Apple will give notice to parties using the API if and when this happens. Examples Export Request The following example demonstrates an export request using the headers and their associated values you pass to the API: POST /iwork/api/v2/export HTTP/1.1 authorization: eyJhbGciOiJFUzI1NiIsImtpZCI6IkIzQ1U3TUhQUzgifQ.eyJlbmNvZGVkX2ZpbGVuYW1lIjoiOEorWWdDQmpiRzkxWk9LWWdTNXVkVzFpWlhKeiIsImV4cG9ydF9mb3JtYXQiOiJjb20uYWRvYmUucGRmIiwiaWF0IjoxNjkzMDA0MDQxLCJpc3MiOiI0M0tUTFlYTTRHIiwiZXhwIjoxNjkzMDExMjQxfQ.4Uw6_WeYZgmi2gXC82tBeSXDGwa2ajouG2tQVgNlWPld0mxTHuc0VSNWDUOr5QlPZqjJYMKEdZ4wpTmEfuuVcg Content-Type: application/octet-stream Host: https://iworkpreviewapi.icloud.com Content-Length: 323927 The filename is “😀 cloud☁.numbers”. Generating a JWT using JSON Object Signing and Encryption (JOSE) For more information on the JOSE NodeJS package, see the JOSE package documentation. import * as jose from 'jose' const alg = 'ES256' const pkcs8 = `-----BEGIN PRIVATE KEY—— MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQg0oCMjI+HiYGjXZCz W8BKk4ZNjutgQbRPLDkD3g47djWgCgYIKoZIzj0DAQehRANCAATtEMfktkJxsvLV zNZtwllVtt7TCpbaDrJE10lM25cF56mRy6RXfwVyuhCqw7xMMzJH+rfciw9+vnZk 4csA9gdr -----END PRIVATE KEY-----` const privateKey = await jose.importPKCS8(pkcs8, alg) const jwt = await new jose.SignJWT({ encoded_filename: Buffer.from('😀 cloud☁.numbers').toString('base64'), export_format: 'com.adobe.pdf' }) .setProtectedHeader({ alg, kid: 'HBLUFDY367' }) .setIssuedAt() .setIssuer('43KTLYXM4G') .setExpirationTime('2h') .sign(privateKey) console.log(jwt) Using the above Apple Developer key, this is the JWT header and payload the package signs: // Header { "alg": "ES256", "kid": "HBLUFDY367" } // Payload { "encoded_filename": "8J+YgCBjbG91ZOKYgS5udW1iZXJz", "export_format": "com.adobe.pdf", "iat": 1693005092, "iss": "43KTLYXM4G", "exp": 1693012292 } And the resulting signed JWT is: eyJhbGciOiJFUzI1NiIsImtpZCI6IkhCTFVGRFkzNjcifQ.eyJlbmNvZGVkX2ZpbGVuYW1lIjoiOEorWWdDQmpiRzkxWk9LWWdTNXVkVzFpWlhKeiIsImV4cG9ydF9mb3JtYXQiOiJjb20uYWRvYmUucGRmIiwiaWF0IjoxNjkzMDA1MDkyLCJpc3MiOiI0M0tUTFlYTTRHIiwiZXhwIjoxNjkzMDEyMjkyfQ.o4haQp-Fo-r_-_rELXhMEbOIXU8n-mr8sAogH8b6i8x9_VdHYnTw29r7hu0OjwA_HWNWfwpBvgLNtqr2dcl4Vg note: The signed JWT can be different for the same input. ## HTTP Body The body of the request. The body contains the iWork document for the service to export in raw binary form. If the original file is a package file, zip it before adding to the request.