Make posts from a recipe
social.posts.generate@2
Starts one run that makes unapproved drafts for several ideas at once. Each idea is a recipe and its answers; every idea is made for each chosen account that can take it, and an account that cannot is that idea's own answer with its reason, never a refusal of the others. Requires Write social. A batch of unpaid recipes works with a script key. A batch with an idea that buys an AI picture waits for one human approval for the whole batch: the member's own Generate action is the yes, and a script key or a connected agent asks once, answering requirements with an approvalRequestRef. Nothing runs until a person approves; replay the same operationId after the approval and the batch starts once under your key's authority. The one yes covers exactly the pictures the answer names (pictures), one for each idea that buys one and has an account that can take it, at most ten; the answer's pictureEstimate is Media's estimate in USD for all of them, not an actual charge or a guaranteed maximum, and writing costs extra. Replaying the same operationId returns the same run and buys nothing twice. Nothing here approves, schedules or publishes. Follow the run with Automation run inspector: its result says, for every idea and account, the saved draft or the reason it was not saved, and one idea that fails leaves every other idea's drafts saved. social.posts.generate@1 stays for one recipe and is the same run of one idea.
Make three posts for two accounts
Replace the YOUR_... values with your own. Each idea is one recipe and its answers; here two use the same setup. Nothing is approved or published.
# 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": "generateIdeas",
"contractRef": "social.posts.generate@2"
},
"operationId": "generate-ideas-1",
"input": {
"ideas": [
{
"key": "monday",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {
"brief": "Lemon drizzle cake is back this week."
}
},
{
"key": "wednesday",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {
"brief": "Our weekend workshop has two seats left."
}
},
{
"key": "friday",
"recipeRef": "YOUR_PHOTO_RECIPE_REF",
"answers": {
"image": {
"resourceRef": "juniper-cakes.drive/files/YOUR_IMAGE_ID",
"contractRef": "YOUR_IMAGE_CONTRACT_REF"
},
"brief": "Our lemon cake on the counter."
}
}
],
"accountRefs": [
{
"businessProfileId": "YOUR_BUSINESS_ID",
"featureId": "juniper-cakes.social",
"collectionId": "juniper-cakes.accounts",
"id": "YOUR_ACCOUNT_ID"
}
]
}
}'
// 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": "generateIdeas",
"contractRef": "social.posts.generate@2"
},
"operationId": "generate-ideas-1",
"input": {
"ideas": [
{
"key": "monday",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {
"brief": "Lemon drizzle cake is back this week."
}
},
{
"key": "wednesday",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {
"brief": "Our weekend workshop has two seats left."
}
},
{
"key": "friday",
"recipeRef": "YOUR_PHOTO_RECIPE_REF",
"answers": {
"image": {
"resourceRef": "juniper-cakes.drive/files/YOUR_IMAGE_ID",
"contractRef": "YOUR_IMAGE_CONTRACT_REF"
},
"brief": "Our lemon cake on the counter."
}
}
],
"accountRefs": [
{
"businessProfileId": "YOUR_BUSINESS_ID",
"featureId": "juniper-cakes.social",
"collectionId": "juniper-cakes.accounts",
"id": "YOUR_ACCOUNT_ID"
}
]
}
}),
},
);
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": "generateIdeas",
"contractRef": "social.posts.generate@2",
},
"operationId": "generate-ideas-1",
"input": {
"ideas": [
{
"key": "monday",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {
"brief": "Lemon drizzle cake is back this week.",
},
},
{
"key": "wednesday",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {
"brief": "Our weekend workshop has two seats left.",
},
},
{
"key": "friday",
"recipeRef": "YOUR_PHOTO_RECIPE_REF",
"answers": {
"image": {
"resourceRef": "juniper-cakes.drive/files/YOUR_IMAGE_ID",
"contractRef": "YOUR_IMAGE_CONTRACT_REF",
},
"brief": "Our lemon cake on the counter.",
},
},
],
"accountRefs": [
{
"businessProfileId": "YOUR_BUSINESS_ID",
"featureId": "juniper-cakes.social",
"collectionId": "juniper-cakes.accounts",
"id": "YOUR_ACCOUNT_ID",
},
],
},
},
timeout=30,
)
print(response.status_code, response.json())
One brief for every idea, with suggested times
The shared brief fills each idea's brief question; period asks for a suggested time for each saved draft. Times are only suggested.
# 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": "generateIdeas",
"contractRef": "social.posts.generate@2"
},
"operationId": "generate-ideas-2",
"input": {
"ideas": [
{
"key": "one",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {}
},
{
"key": "two",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {}
}
],
"sharedBrief": {
"brief": "Spring menu is live."
},
"accountRefs": [
{
"businessProfileId": "YOUR_BUSINESS_ID",
"featureId": "juniper-cakes.social",
"collectionId": "juniper-cakes.accounts",
"id": "YOUR_ACCOUNT_ID"
}
],
"period": {
"from": "2027-03-01T00:00:00Z",
"to": "2027-03-15T00:00:00Z",
"timeZone": "America/Denver"
}
}
}'
// 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": "generateIdeas",
"contractRef": "social.posts.generate@2"
},
"operationId": "generate-ideas-2",
"input": {
"ideas": [
{
"key": "one",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {}
},
{
"key": "two",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {}
}
],
"sharedBrief": {
"brief": "Spring menu is live."
},
"accountRefs": [
{
"businessProfileId": "YOUR_BUSINESS_ID",
"featureId": "juniper-cakes.social",
"collectionId": "juniper-cakes.accounts",
"id": "YOUR_ACCOUNT_ID"
}
],
"period": {
"from": "2027-03-01T00:00:00Z",
"to": "2027-03-15T00:00:00Z",
"timeZone": "America/Denver"
}
}
}),
},
);
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": "generateIdeas",
"contractRef": "social.posts.generate@2",
},
"operationId": "generate-ideas-2",
"input": {
"ideas": [
{
"key": "one",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {},
},
{
"key": "two",
"recipeRef": "YOUR_RECIPE_REF",
"answers": {},
},
],
"sharedBrief": {
"brief": "Spring menu is live.",
},
"accountRefs": [
{
"businessProfileId": "YOUR_BUSINESS_ID",
"featureId": "juniper-cakes.social",
"collectionId": "juniper-cakes.accounts",
"id": "YOUR_ACCOUNT_ID",
},
],
"period": {
"from": "2027-03-01T00:00:00Z",
"to": "2027-03-15T00:00:00Z",
"timeZone": "America/Denver",
},
},
},
timeout=30,
)
print(response.status_code, response.json())
Try an idea again
Use the run of the earlier, finished batch and the idea's key. Only the accounts that still lack a draft are made.
# 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": "generateIdeas",
"contractRef": "social.posts.generate@2"
},
"operationId": "generate-ideas-3",
"input": {
"retryOf": {
"runRef": "11111111-2222-4333-8444-555555555555",
"ideaKeys": [
"wednesday"
]
}
}
}'
// 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": "generateIdeas",
"contractRef": "social.posts.generate@2"
},
"operationId": "generate-ideas-3",
"input": {
"retryOf": {
"runRef": "11111111-2222-4333-8444-555555555555",
"ideaKeys": [
"wednesday"
]
}
}
}),
},
);
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": "generateIdeas",
"contractRef": "social.posts.generate@2",
},
"operationId": "generate-ideas-3",
"input": {
"retryOf": {
"runRef": "11111111-2222-4333-8444-555555555555",
"ideaKeys": [
"wednesday",
],
},
},
},
timeout=30,
)
print(response.status_code, response.json())
Parameters
What goes in input:
| Name | Type | Required | Description |
|---|---|---|---|
ideas |
array of object | No | One to twenty ideas, in the order you want them. Leave out when you use retryOf. |
ideas[].key |
string | Yes | A name for the idea, up to 64 letters, digits, ., _ or -, unique in the batch and kept the same when you try the idea again. |
ideas[].recipeRef |
string | Yes | The content setup to make it with, by its reference. The same setup may appear in several ideas. |
ideas[].answers |
object | Yes | Your answers to that setup's questions, by question. A question the shared brief fills may be left out. |
sharedBrief |
object | No | One set of words for every idea, by question role, such as brief, audience or call-to-action. Each idea's unanswered questions of that role are filled; a role a setup does not ask, such as a photo, stays with the idea, and an idea's own answer is never replaced. |
accountRefs |
array of object | No | The accounts to make drafts for, 1 to 10, each listed once. Ideas times accounts may be at most 100. With retryOf, leave out to use the accounts that still lack a draft, or name some to narrow it. For a paid picture, their identities, labels, platforms and handles are frozen with the yes; if they change before the batch starts, review them and start a new request. |
accountRefs[].businessProfileId |
string | Yes | Your business's id. |
accountRefs[].featureId |
string | Yes | The featureId of the account's row. |
accountRefs[].collectionId |
string | Yes | The collectionId of the account's row. |
accountRefs[].id |
string | Yes | The account's id. |
period |
object | No | Ask for suggested times. Each saved draft is given a time from its own account's posting times in this period, ideas in order, one idea a day. A suggestion is not a placement: nothing is approved or scheduled, and a draft with no time left or an account with no posting times is listed unplaced with the reason. |
period.from |
string | Yes | The start of the period, an instant with its offset. |
period.to |
string | Yes | The end of the period, an instant with its offset; at most 62 days after the start. |
period.timeZone |
string | Yes | The business time zone the posting times are in, such as America/Denver; read it from the business, it is not looked up here. |
retryOf |
object | No | Try ideas of an earlier, finished batch of this workspace again, using the recipe and answers each was admitted with, never today's defaults. Only accounts that have no draft of the idea are made. An idea that needs a picture is a new request with its own yes. |
retryOf.runRef |
string | Yes | The earlier batch's run. |
retryOf.ideaKeys |
array of string | Yes | The ideas to try again, by key, each once. |
Response
A call that worked answers 200 with an applied receipt; its output holds these fields, among others. GET /catalog/social.posts.generate@2 answers the complete shape as JSON Schema.
| Name | Type | Description |
|---|---|---|
runRef |
string | The run that is making the drafts: follow it with Automation run inspector. |
featureId |
string | The feature the run belongs to. |
ideaKeys |
array of string | The ideas started, in order. |
pictures |
integer | How many AI pictures the one yes covers: one for each idea that buys a picture and has an account that can take it. 0 for a batch that buys none. |
paidProduction |
object | Present when pictures is above 0: the declared production the yes covers once for each of those ideas, through the declared image role, with no paid retry or fallback. |
pictureEstimate |
object | Present when pictures is above 0: Media's estimated cost of all those pictures in USD, writing extra. Not a bill, total or guaranteed maximum. The member call or exact approved agent request is the yes. |
{
"status": "applied",
"operationId": "generate-ideas-1",
"output": {
"runRef": "11111111-2222-4333-8444-555555555555",
"featureId": "juniper-cakes.automations",
"ideaKeys": [
"monday",
"wednesday",
"friday"
],
"pictures": 0
}
}
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 |
|---|---|---|
APPROVAL.REQUIRED |
requirements |
The batch has an idea that buys a picture: the answer is requirements with an approvalRequestRef, asked once for the whole batch. Replay the same operationId after a person approves. Nothing runs, and nothing is spent, until then; a declined or expired request makes nothing. |
SOCIAL.BATCH_TOO_MANY_PICTURES |
rejected |
More than ten ideas buy a picture. Nothing is started. |
SOCIAL.BATCH_TOO_LARGE |
rejected |
Ideas times accounts is more than 100. |
SOCIAL.BATCH_NOTHING_TO_MAKE |
rejected |
No chosen account can take any of the ideas; the reasons are in the message. |
SOCIAL.BATCH_INPUT_INVALID |
rejected |
Neither ideas with accountRefs nor retryOf was given, or both were. |
SOCIAL.IDEA_DUPLICATE |
rejected |
Two ideas have the same key. |
SOCIAL.IDEA_ANSWERS_INVALID |
rejected |
An idea's answers do not fit its setup's questions; the path names the idea. |
SOCIAL.RECIPE_UNAVAILABLE |
rejected |
An idea's recipeRef is not a content setup this business can use. |
SOCIAL.RETRY_NOT_AVAILABLE |
rejected |
retryOf.runRef is not one of this workspace's finished batches. |
SOCIAL.RETRY_NOTHING_LEFT |
rejected |
Every account already has a draft of the idea. |
SOCIAL.ACCOUNT_DUPLICATE |
rejected |
An account is listed twice. |
DATA.ROW_NOT_FOUND |
rejected |
No such account here for this key. |
MEDIA.PICTURE_APPROVAL_REQUIRED |
rejected |
The caller cannot ask a person for the yes (an automation step, say). Start the batch in GrowLocal, with a script key or through a connected agent. |