Suggest a time for a draft

social.edition.propose@1

Suggest a time for a draft, or take the suggestion back. Requires Write social. A suggestion is two cells beside the post: it never approves, schedules or posts anything, moves no approval or approval digest, and a draft that is not approved can never be placed by suggesting a time for it. Approving later keeps the suggested time; scheduling is still your own action, and placing the post takes the suggestion back.

Suggest a time for a draft

The draft keeps its status and approval; only the suggestion is written. Send the revision you read. Send "proposedAt": null with no zone to take it back.

# A new operationId for each new request; the same one to retry it.
curl https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations \
  -H "Authorization: Bearer gl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "featureId": "YOUR_FEATURE_ID",
    "export": "proposeEdition",
    "contractRef": "social.edition.propose@1"
  },
  "operationId": "propose-time-1",
  "input": {
    "edition": {
      "ref": {
        "businessProfileId": "YOUR_BUSINESS_ID",
        "featureId": "juniper-cakes.data",
        "collectionId": "juniper-cakes.editions",
        "id": "YOUR_EDITION_ID"
      },
      "revision": 1
    },
    "proposedAt": "2031-06-03T16:00:00Z",
    "displayTimeZone": "America/Phoenix"
  }
}'
// A new operationId for each new request; the same one to retry it.
const response = await fetch(
  "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer gl_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "target": {
        "featureId": "YOUR_FEATURE_ID",
        "export": "proposeEdition",
        "contractRef": "social.edition.propose@1"
      },
      "operationId": "propose-time-1",
      "input": {
        "edition": {
          "ref": {
            "businessProfileId": "YOUR_BUSINESS_ID",
            "featureId": "juniper-cakes.data",
            "collectionId": "juniper-cakes.editions",
            "id": "YOUR_EDITION_ID"
          },
          "revision": 1
        },
        "proposedAt": "2031-06-03T16:00:00Z",
        "displayTimeZone": "America/Phoenix"
      }
    }),
  },
);
const receipt = await response.json();
console.log(response.status, receipt);
import requests

# A new operationId for each new request; the same one to retry it.
response = requests.post(
    "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
    headers={"Authorization": "Bearer gl_YOUR_API_KEY"},
    json={
        "target": {
            "featureId": "YOUR_FEATURE_ID",
            "export": "proposeEdition",
            "contractRef": "social.edition.propose@1",
        },
        "operationId": "propose-time-1",
        "input": {
            "edition": {
                "ref": {
                    "businessProfileId": "YOUR_BUSINESS_ID",
                    "featureId": "juniper-cakes.data",
                    "collectionId": "juniper-cakes.editions",
                    "id": "YOUR_EDITION_ID",
                },
                "revision": 1,
            },
            "proposedAt": "2031-06-03T16:00:00Z",
            "displayTimeZone": "America/Phoenix",
        },
    },
    timeout=30,
)
print(response.status_code, response.json())

Parameters

What goes in input:

Name Type Required Description
edition object Yes The draft to suggest a time for, as you last read it. A post that already holds a placement is refused: move the placement instead.
edition.ref object Yes The draft's row.
edition.ref.businessProfileId string Yes The business that owns it.
edition.ref.featureId string Yes The editions Data feature.
edition.ref.collectionId string Yes The editions table.
edition.ref.id string Yes The row id.
edition.revision integer Yes The revision you read it at; refused if it changed since.
proposedAt string or null Yes The moment to suggest, an instant with its offset, still ahead; null takes the suggestion back.
displayTimeZone string No The time zone the time is shown in, such as America/Denver. Required with a time, refused with null.

Response

A call that worked answers 200 with an applied receipt; its output holds these fields, among others. GET /catalog/social.edition.propose@1 answers the complete shape as JSON Schema.

Name Type Description
ref object The draft's reference.
revision integer Its revision after this call; unchanged when the call changed nothing.
account object The account it is for.
account.label string The account's name.
account.platform one of facebook, instagram, linkedin, x, tiktok, youtube, pinterest, threads, bluesky Its platform.
account.handle string Its handle on the platform.
account.connected boolean Whether the account is still connected.
account.textPost object Whether this platform accepts a text-only post, independently of whether the account is connected.
account.textPost.compatible boolean True when the connector accepts a post with no media.
account.textPost.reason string The plain reason when text-only posting is incompatible; omitted otherwise.
caption string The caption.
mediaRefs array of string The media, in order.
format one of post, story, reel post, story or reel.
notes string The internal notes.
source object or null Where the content came from, or null.
proposedAt string The suggested time, an instant in UTC; absent after a suggestion is taken back.
proposedZone string The time zone the suggested time is shown in; present with proposedAt.
createdAt string When it was made.
createdBy string or null Who made it, or null.
contentDigest string The digest of the content an approval stands on; a suggested time is no part of it.
approval object The draft's approval, exactly as it was: suggesting a time never approves, invalidates or changes it.
approval.state one of none, approved, invalidated none, approved or invalidated; the same before and after.
publication object or null null: suggesting a time never places the draft. A draft that is already placed is refused.
status one of draft, approved, scheduled, suspended, held, dispatching, accepted, published, failed, uncertain Where the draft is. Suggesting a time never changes it: a draft stays draft and an approved draft stays approved.
canEdit boolean Whether you may edit it.
canApprove boolean Whether you may approve it.
canSchedule boolean Whether you may schedule it: only an approved draft can be scheduled, whatever time is suggested.
canCancel boolean Whether you may cancel it.
canRemove boolean Whether you may remove it.
canPropose boolean Whether you may suggest a time for it now: it holds no placement and this operation admits you.
{
  "status": "applied",
  "operationId": "propose-time-1",
  "output": {
    "ref": {
      "businessProfileId": "YOUR_BUSINESS_ID",
      "featureId": "juniper-cakes.data",
      "collectionId": "juniper-cakes.editions",
      "id": "YOUR_EDITION_ID"
    },
    "revision": 1,
    "account": {
      "ref": {
        "businessProfileId": "YOUR_BUSINESS_ID",
        "featureId": "juniper-cakes.social",
        "collectionId": "juniper-cakes.accounts",
        "id": "YOUR_ACCOUNT_ID"
      },
      "revision": 1,
      "label": "Juniper Cakes",
      "platform": "x",
      "handle": "junipercakes",
      "connected": true,
      "textPost": {
        "compatible": true
      },
      "constraints": null
    },
    "caption": "This week: lemon drizzle, fresh from the oven.",
    "mediaRefs": [],
    "format": "post",
    "platformOptions": {},
    "notes": "",
    "source": null,
    "createdAt": "2026-11-13T09:30:00Z",
    "createdBy": null,
    "contentDigest": "0000000000000000000000000000000000000000000000000000000000000000",
    "approval": {
      "state": "none",
      "digest": null,
      "approvedAt": null,
      "approvedBy": null,
      "review": null
    },
    "publication": null,
    "status": "draft",
    "canEdit": true,
    "canApprove": true,
    "canSchedule": false,
    "canPropose": true,
    "canCancel": false,
    "canRemove": true,
    "proposedAt": "2031-06-03T16:00:00Z",
    "proposedZone": "America/Phoenix"
  }
}

Errors

Besides the answers every request can get (Errors), its receipt can say:

Status HTTP What it means
pending 202 Accepted and still running. Look it up with GET /operations/{operationId}.
uncertain 202 GrowLocal can't yet tell whether it took effect. Look it up before trying again.
requirements 409 Something must happen first; the receipt lists what.
conflict 409 The row changed since you read it, or this operationId was used with a different body.
rejected 400, or 403 when it's a matter of access Not done. diagnostics says why: each has a code, a path into what you sent and a message.

The codes in diagnostics you're most likely to see:

Code Status What it means
SOCIAL.PROPOSAL_PAST rejected The suggested moment is not ahead.
SOCIAL.PROPOSAL_PLACED rejected The post already has a placement; move that instead.
SOCIAL.TIME_ZONE_REQUIRED rejected A time was suggested without the zone it is shown in.
SOCIAL.TIME_ZONE_UNEXPECTED rejected A zone was sent with null.
SOCIAL.TIME_ZONE_UNKNOWN rejected The zone is not a real IANA time zone.
SOCIAL.REVISION_CONFLICT conflict The draft changed since expectedRevision was read.