post/file-upload-intentsWrite operation

Reserve and create a private file upload intent

Reserves workspace storage and returns a short-lived private HTTPS PUT target bound to the exact content length, MIME type, destination, credential, and idempotency key.

Required scopes

files:write

Request example

curl --request POST \
  --url 'https://api.de.teamgrid.app/v1/file-upload-intents' \
  --header 'Authorization: Bearer $TEAMGRID_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "destination": {
      "id": "string",
      "type": "contact"
    },
    "file": {
      "fileName": "string",
      "mimeType": "string",
      "size": 0
    }
  }'

const response = await fetch('https://api.de.teamgrid.app/v1/file-upload-intents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TEAMGRID_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "destination": {
    "id": "string",
    "type": "contact"
  },
  "file": {
    "fileName": "string",
    "mimeType": "string",
    "size": 0
  }
}),
})

const result = await response.json()

type ApiResponse = unknown

const response = await fetch('https://api.de.teamgrid.app/v1/file-upload-intents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TEAMGRID_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "destination": {
    "id": "string",
    "type": "contact"
  },
  "file": {
    "fileName": "string",
    "mimeType": "string",
    "size": 0
  }
}),
})

const result: ApiResponse = await response.json()

teamgrid file-upload-intents create \
  --data @payload.json \
  --idempotency-key REQUEST_KEY

Example response 2xx

{
  "data": {
    "attributes": {
      "file": {
        "fileName": "string",
        "mimeType": "string",
        "size": 0
      },
      "transfer": {
        "expiresAt": "2026-07-29T09:00:00.000Z",
        "headers": {
          "content-length": "string",
          "content-type": "string",
          "x-amz-acl": "string"
        },
        "id": "string",
        "maxSize": null,
        "method": "GET",
        "url": "example"
      }
    },
    "id": "string",
    "type": null
  },
  "meta": {
    "requestId": "string"
  }
}

EndpointGerman region

Interactive request builder

Prepare this request

Build locally · nothing is sent

Region

Credential variable

Idempotency-Keyheader · required

JSON request bodyValid JSON

Generated cURL

The builder does not execute requests or persist credentials. Replace the environment-variable placeholder only in your terminal or secret-aware runtime.

Headers

Idempotency-Keyrequired

string

Unique request key retained for seven days. Within that window, reuse with different data is rejected.

Request body

application/json

required

object

The destination associated with this file upload intent.

required

FileTransferMetadata

The file associated with this file upload intent.

Responses

201The request to reserve and create a private file upload intent created the resource. The response contains its canonical public representation and request metadata.application/json

Response schemaapplication/json

required

FileUploadIntent

Public API representation of file upload intent.

required

ResponseMeta

Public API representation of meta.

400The request is invalid.application/json

Response schemaapplication/json

required

array<ApiError>

The errors associated with this error.

required

ResponseMeta

Request metadata, including the request identifier and pagination state when applicable.

401The bearer credential is missing, invalid, expired, or revoked.application/json

Response schemaapplication/json

required

array<ApiError>

The errors associated with this error.

required

ResponseMeta

Request metadata, including the request identifier and pagination state when applicable.

403The credential has insufficient scope.application/json

Response schemaapplication/json

required

array<ApiError>

The errors associated with this error.

required

ResponseMeta

Request metadata, including the request identifier and pagination state when applicable.

409The request conflicts with the current resource state.application/json

Response schemaapplication/json

required

array<ApiError>

The errors associated with this error.

required

ResponseMeta

Request metadata, including the request identifier and pagination state when applicable.

410The upload reservation expired.application/json

Response schemaapplication/json

required

array<ApiError>

The errors associated with this error.

required

ResponseMeta

Request metadata, including the request identifier and pagination state when applicable.

415The active or executable upload type is blocked.application/json

Response schemaapplication/json

required

array<ApiError>

The errors associated with this error.

required

ResponseMeta

Request metadata, including the request identifier and pagination state when applicable.

429The credential or source exceeded its rate limit.application/json

Response schemaapplication/json

required

array<ApiError>

The errors associated with this error.

required

ResponseMeta

Request metadata, including the request identifier and pagination state when applicable.

502The cell-local application returned an invalid response.application/json

Response schemaapplication/json

required

array<ApiError>

The errors associated with this error.

required

ResponseMeta

Request metadata, including the request identifier and pagination state when applicable.

503A required cell-local dependency is unavailable.application/json

Response schemaapplication/json

required

array<ApiError>

The errors associated with this error.

required

ResponseMeta

Request metadata, including the request identifier and pagination state when applicable.

Operation IDcreateFileUploadIntentOpenAPI JSON ↗

Documentation feedbackWas this page useful?