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. |