Social Agent API

    The Social Agent runs a business's social media pages: it makes posts in the business's own frames for the owner to approve, sends them to the connected networks, pulls comments and messages into one inbox and reports reach and engagement.

    Through the API your code reads and decides its drafts, sees where each post went and how it did, and answers the inbox.

    What the Social Agent does and its plan

    The Social Agent plan, one for each business. The price is on the plans page.

    New to the API? Start with Getting started: the key, the address, the errors and the limits.

    Getting started with this agent

    These are done in the Fly app, signed in, because the API cannot do them.

    1. Connect the social accounts in the app, on the Social page under Accounts. The API cannot connect an account. The tool fly_connect_links with kinds set to ["social"] gives the social connect page, which opens without signing in, to hand to whoever manages the accounts. In the app: Social.
    2. Choose the Social Agent plan. Switching the agent on without it is refused. In the app: Billing.
    3. Make a key on the AI assistants page and give it the Social Agent. In the app: AI assistants.
    4. Switch it on for the location with the settings op on the account page: changes.enabled_checks.social_agent set to true.

    The working loop

    1. Find the location: GET /v1/workspaces lists each location with its location_id; agents_on holds "social" where the Social Agent is switched on.
    2. Read the agent's home: POST /v1/tools/fly_home with location_id and agent "social" answers the Social Agent's cards that need the owner (cards.needs_you), the ones in flight, its recent activity, rank and health.
    3. Decide each card: POST /v1/locations/{location_id}/ops/respond with the card's id as action_id and a decision (approve, reject, done, dismiss, submit, change or undo_dismiss). The tool fly_card gives one card whole first.
    4. Read its report: POST /v1/tools/fly_report with agent "social" and from and to dates (YYYY-MM-DD) answers the headline numbers, each section and the first rows of each table; the op social_report on the account page answers the report whole.
    The Social Agent's home
    curl -X POST https://www.fly-social.com/api/v1/tools/fly_home \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{"location_id":"3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84","agent":"social"}'

    The Social Agent's drafts

    The agent writes drafts for the owner to decide. social_drafts reads them with every network each one goes to; social_draft_decision approves or rejects one; the rest move it, post it now, change its words or redraw its picture or slides.

    The Social Agent's drafts
    OperationKindWhat it doesParams
    social_draftsReadThe Social Agent's drafts.{}
    social_draft_decisionWriteApprove or reject a social draft; approve with when: now to post at once.{ social_post_id, decision: approve | reject, when?: now }
    social_draft_whenWriteMove a social draft to a time, or post it now.{ social_post_id, scheduled_at } | { social_post_id, when: now }
    social_draft_refineWriteRefine a social draft's words (an instruction, or the words per network).{ social_post_id, platforms?, instruction } | { social_post_id, words: { network: text } }
    social_draft_redrawWriteDraw a social draft's picture again.{ social_post_id, instruction? }
    social_draft_slide_orderWriteReorder a carousel's slides.{ social_post_id, order: string[] }
    social_draft_slide_refineWriteRedraw one slide with an instruction.{ social_post_id, slide, instruction }

    Example: Approve a draft

    POST /v1/locations/{location_id}/ops/social_draft_decision
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/social_draft_decision \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: social-8d3b5f2a-approve-1" \
      -d '{"social_post_id":"8d3b5f2a-6c9e-4a1d-b7f4-3e6a9c2d5b18","decision":"approve"}'

    The answer. ok, the post_status, the scheduled_at it goes out at and its targets. A rejected draft answers post_status cancelled; a draft already decided answers 409 with the reason.

    Where posts go and how they went

    The networks a post may go to, each network's own caption, how a post went on each network (and a retry on one), and the posts that went live in the last 90 days with their numbers. A Google post made with create_post on the Local Agent page goes to these networks too with social_targets.

    Where posts go and how they went
    OperationKindWhat it doesParams
    social_targetsReadThe networks a post may also go to.{}
    social_captionsWriteEach network's own caption for a post (AI).{ text, networks: string[] }
    social_post_statusReadHow a post went on each network.{ social_post_id }
    social_post_retryWriteTry a post again on one network.{ social_post_id, platform }
    social_timelineReadThe posts that went live across networks in the last 90 days, with their numbers.{}
    tiktok_creator_infoReadTikTok's creator choices before a direct post.{ account_id, media: video | photo }

    Example: How a post went

    POST /v1/locations/{location_id}/ops/social_post_status
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/social_post_status \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{"social_post_id":"8d3b5f2a-6c9e-4a1d-b7f4-3e6a9c2d5b18"}'

    The answer. How the post went on each network.

    Comments and messages

    The social inbox holds the comments, messages and mentions of the connected accounts. Read it a page at a time, draft a reply (AI), reply, hide an item or mark it, and set how the agent replies on a post.

    Comments and messages
    OperationKindWhat it doesParams
    inbox_listReadThe social inbox: comments and messages.{ status?: open | replied | hidden | ignored, kind?: comment | message | mention, cursor?, limit?, post_id? }
    inbox_draftWriteDraft a reply to an inbox item (AI).{ item_id }
    inbox_replyWriteReply to an inbox item.{ item_id, text }
    inbox_hideWriteHide an inbox item.{ item_id }
    inbox_markWriteMark an inbox item ignored or open.{ item_id, status: ignored | open }
    social_post_reply_settingsWriteAuto-reply on or off for a post (or as the account), and its reply instructions.{ social_post_id, reply_mode?: on | off | account, reply_instructions? }

    Example: The open comments and messages

    POST /v1/locations/{location_id}/ops/inbox_list
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/inbox_list \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{"status":"open","limit":20}'

    The answer. items, newest first, counts by status (open, replied, hidden, ignored) and next_cursor for the next page.

    What the agent makes

    The Social plan's posts and replies left this month, the videos, Stories, carousels and text posts it makes, and the week's reel brief sent to a creator.

    What the agent makes
    OperationKindWhat it doesParams
    social_allowanceReadThe Social plan's posts and replies this month.{}
    social_video_settingsWriteVideos a week, Stories, carousels, text posts and the reel voice (read with none of them).{ social_videos_per_week?: 0 | 1 | 2 | 3, social_stories?: boolean, social_carousels?: boolean, social_text_posts?: boolean, social_reel_voice?: boolean }
    social_reel_brief_emailWriteEmail the week's reel brief to the creator (the reel brief card's id).{ action_id, email }

    Example: This month's posts and replies

    POST /v1/locations/{location_id}/ops/social_allowance
    curl -X POST https://www.fly-social.com/api/v1/locations/3f6c2b1e-8d4a-4c7e-9b2f-1a5d7e9c0b84/ops/social_allowance \
      -H "Authorization: Bearer fmk_your_key" \
      -H "Content-Type: application/json" \
      -d '{}'

    The answer. The Social plan's posts and replies this month.