Create or verify the enrolled native Sheets destination

POST

/v1/pilot/destinations

• The private service origin. Reachable only over a Cloudflare service binding from within the account — not from the public internet, and not from a browser. No public base URL is assigned yet; when one is, it replaces this entry.

Requires sync:write. Accepts only the destination ID. The service reserves one creation attempt before calling Google, persists the returned workbook ID and verifies its reserved layout. An active replay verifies and returns the existing workbook without creating another. A known paused workbook may retry verification; an unknown creation outcome remains paused and returns destination_creation_unconfirmed for operator review. Implemented and locally tested; new live scheduled delivery and controlled failure/recovery acceptance remain pending.

Authorizations

• bearerAuth

Request Body ^required

The destination and runtime drive.file grant must already be enrolled by an operator. No credentials are accepted by this route.

object

destinationId

required

string

/^[A-Za-z0-9_-]{1,128}$/

Responses

200

Create or verify the enrolled native Sheets destination.

object

destinationId

required

string

/^[A-Za-z0-9_-]{1,128}$/

state

required

string

Allowed value: active

spreadsheetId

required

string

/^[A-Za-z0-9_-]{1,128}$/

url

required

The URL contains exactly the returned spreadsheetId.

string format: uri

/^https://docs\.google\.com/spreadsheets/d/[A-Za-z0-9_-]{1,128}/edit$/

400

invalid_json for malformed JSON; invalid_request for a query delimiter or non-exact destination body.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed values: invalid_request invalid_json invalid_schedule

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

401

Missing, expired, revoked or reassigned key, including changes before response release.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed value: unauthorized

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

Headers

WWW-Authenticate

required

string

Allowed value: Bearer

403

forbidden for key scope; destination_permission_required when the current Sheets grant is absent.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed values: forbidden source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

404

destination_not_found in this workspace.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed values: not_found destination_not_found schedule_not_found pipeline_not_found connection_unavailable

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

405

method_not_allowed — use the method named in Allow.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed value: method_not_allowed

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

Headers

Allow

required

string

Allowed value: POST

409

destination_conflict, destination_creation_unconfirmed, or sheet_layout_conflict.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed values: destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

413

Request JSON exceeds 4096 bytes.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed value: request_too_large

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

415

Use application/json with no Content-Encoding other than identity.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed values: unsupported_media_type unsupported_encoding

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

502

Google authentication or workbook verification read failed; no raw provider text is returned.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed values: provider_auth_failed provider_unavailable

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

503

credential_configuration_unavailable, credential_unavailable, credential_busy, provider_rate_limited, or automation_unavailable.

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_json invalid_schedule unsupported_media_type unsupported_encoding request_too_large unauthorized forbidden not_found method_not_allowed destination_not_found schedule_not_found pipeline_not_found connection_unavailable source_permission_required destination_permission_required schedule_enable_forbidden schedule_inactive destination_conflict destination_creation_unconfirmed destination_unavailable timezone_unverified timezone_conflict schedule_conflict redrive_conflict sheet_capacity_exhausted sheet_layout_conflict credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_auth_failed provider_rate_limited provider_unavailable automation_unavailable

message

required

string

error

object

code

Allowed values: credential_configuration_unavailable automation_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable

error

object

code

Allowed values: invalid_request invalid_json unauthorized forbidden destination_permission_required destination_not_found method_not_allowed destination_conflict destination_creation_unconfirmed sheet_layout_conflict request_too_large unsupported_media_type unsupported_encoding provider_auth_failed provider_unavailable credential_configuration_unavailable credential_unavailable credential_busy provider_rate_limited automation_unavailable