Drive API Quickstart

This quickstart shows the safest path from "I want an integration" to a working Drive API call. You will create a narrow token, list Drive spaces, upload one file, and create a public share link with an expiry date.

1. Create a Drive token

Open AI Agents & API → Tokens → Create token. Give the token a clear name such as drive-report-uploader. Select only the scopes required by your workflow.

For this guide, use:

• drive:account:read
• drive:account:write
• drive:account:share

Do not include purge scopes for a first integration. Keep permanent delete in a separate maintenance token.

Copy the token immediately after creation. TrekMail shows the plaintext once and stores only a secure hash.

2. Set your base URL and token

export TREKMAIL_BASE_URL="https://trekmail.net"
export TREKMAIL_API_TOKEN="tm_live_your_token"

Every request uses the same bearer header:

-H "Authorization: Bearer $TREKMAIL_API_TOKEN"

3. List available Drive spaces

curl -s "$TREKMAIL_BASE_URL/api/v1/drive/spaces" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN"

The response includes Account Drive and any mailbox Drive spaces the token is allowed to see. Use account for Account Drive in the next examples.

4. Create a folder

Write operations should include an idempotency key. If your network retries the request, TrekMail can return the original result instead of creating duplicates.

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/folders" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: folder-$(date +%s)" \
  -d '{"name":"API Uploads","color":"#2563eb"}'

Save the returned folder ID.

5. Upload a file

The REST API separates upload negotiation from file transfer. First initiate:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/spaces/account/uploads:initiate" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-report-001" \
  -d '{"name":"report.pdf","size_bytes":123456,"folder_id":42,"client_mime":"application/pdf"}'

TrekMail returns upload instructions. Send the bytes to the returned upload URL, then call:

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/uploads/{FILE_ID}:complete" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

If you use MCP, prefer drive_file_upload. It wraps the initiate, transfer, complete, and abort steps in one tool.

6. Create a share link

curl -s -X POST "$TREKMAIL_BASE_URL/api/v1/drive/files/{FILE_ID}/share-links" \
  -H "Authorization: Bearer $TREKMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: share-report-001" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","max_downloads":25}'

The returned public URL is the only time the raw link token is shown. Store it now if you need to send it later.

7. Check the audit trail

Open AI Agents & API → Audit Log and filter by token. You should see folder creation, upload, completion, and share-link creation. This is the fastest way to confirm that your integration is using the expected token and scopes.

Production checklist

• Use one token per integration.
• Grant read/write/share separately; keep purge out of daily workflows.
• Add expiry and download caps to public links.
• Use idempotency keys for all POST, PATCH, and destructive DELETE requests.
• Revoke test tokens after development.