> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onlyfansapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Add to Story (/api-reference/stories/add-to-story)
Post a new media or vault file to your story, optionally with text overlays, @mentions, and a question sticker. Overlay elements are rendered by OnlyFans on top of your story media at view time.
## OpenAPI
````yaml https://app.onlyfansapi.com/scribe-docs/openapi.yaml post /api/{account}/stories
openapi: 3.0.3
info:
title: OnlyFans API
description: ""
version: 1.0.0
servers:
- url: https://app.onlyfansapi.com
security:
- default: []
tags:
- name: API Keys
description: ""
- name: Account
description: Endpoints for your linked accounts
- name: Analytics - Financial
description: APIs for retrieving financial analytics data
- name: Analytics - Summary
description: APIs for retrieving summary analytics data
- name: Banking
description: Operations related to user banking details, payout methods, legal
and tax information, and account country settings.
- name: Banned Words
description: Reference list of OnlyFans banned words used by the
`blockBannedWords` screening parameter
- name: Blocked / Restricted Users
description: APIs for listing the users an account has blocked or restricted
- name: Chargebacks
description: ""
- name: Chat Messages
description: ""
- name: Chats
description: ""
- name: Client Sessions
description: ""
- name: Connect OnlyFans Account
description: ""
- name: Data Exports
description: APIs for managing data exports
- name: Endpoints
description: ""
- name: Engagement / Messages
description: ""
- name: Fans
description: APIs for managing OnlyFans fans (subscribers)
- name: Fans - AI Summary
description: APIs for generating and retrieving AI-powered fan profile summaries
- name: Following
description: APIs for managing OnlyFans followings (people you're subscribed to)
- name: Free Trial Links
description: APIs for managing Free Trial Links
- name: Giphy
description: ""
- name: Link Tags
description: APIs for managing tags on free trial links, tracking links, and Smart Links
- name: Mass Messaging
description: ""
- name: Media
description: ""
- name: Media Vault
description: ""
- name: Media Vault Lists
description: ""
- name: Notifications
description: Endpoints for managingr account notifications
- name: Payouts
description: ""
- name: Post Comments
description: ""
- name: Post Labels
description: APIs for managing your post labels
- name: Posts
description: APIs for managing OnlyFans posts
- name: Promotions
description: ""
- name: Public Profiles
description: ""
- name: Queue
description: ""
- name: Release Forms
description: APIs for managing OnlyFans release forms
- name: Saved For Later (Messages)
description: ""
- name: Saved For Later (Posts)
description: ""
- name: Settings
description: ""
- name: Shared Free Trial Links
description: APIs for Free Trial Links that other OF creators have shared with
this account. Revenue, cost, and spender data are not available for shared
links.
- name: Shared Tracking Links
description: APIs for Tracking Links (campaigns) that other OF creators have
shared with this account. Revenue, cost, and spender data are not
available for shared campaigns.
- name: Smart Link Postbacks
description: APIs for managing Smart Link postback destinations
- name: Smart Links
description: APIs for managing Smart Links (Free Trial Links and Tracking Links
with pooled inventory)
- name: Statistics
description: ""
- name: Stored Free Trial Links
description: Instant APIs for retrieving stored free trial links from the
OnlyFansAPI Cache (free, no credits used)
- name: Stored Shared Free Trial Links
description: Instant APIs for retrieving stored shared Free Trial Links from the
OnlyFansAPI Cache (free, no credits used)
- name: Stored Shared Tracking Links
description: Instant APIs for retrieving stored shared Tracking Links
(campaigns) from the OnlyFansAPI Cache (free, no credits used)
- name: Stored Tracking Links
description: Instant APIs for retrieving stored tracking links from the
OnlyFansAPI Cache (free, no credits used)
- name: Stories
description: APIs for managing OnlyFans stories
- name: Story Highlights
description: APIs for managing OnlyFans story highlights
- name: Subscription Bundles
description: ""
- name: Tracking Links
description: APIs for managing tracking links
- name: Transactions
description: APIs for managing OnlyFans transactions
- name: Usage
description: Credit usage reporting for your team
- name: User List Collections
description: ""
- name: Users
description: APIs for fetching OnlyFans users
- name: Webhooks
description: ""
paths:
/api/{account}/stories:
parameters:
- in: path
name: account
description: The Account ID
example: acct_XXXXXXXXXXXXXXX
required: true
schema:
type: string
post:
summary: Add to Story
operationId: addToStory
description: Post a new media or vault file to your story, optionally with text
overlays, @mentions, and a question sticker. Overlay elements are
rendered by OnlyFans on top of your story media at view time.
parameters: []
responses:
"200":
description: Success
content:
application/json:
schema:
type: object
example:
data:
id: 123
userId: 123
isReady: false
hasPost: false
isWatched: false
media:
- id: 123
type: photo
convertedToVideo: false
canView: true
hasError: false
createdAt: 2025-01-01T01:01:01+00:00
isReady: false
files:
full:
url: null
width: 0
height: 0
size: 0
sources: []
thumb: null
preview: null
squarePreview: null
duration: 0
hasCustomPreview: false
createdAt: 2025-01-01T01:01:01+00:00
canvasWidth: 1080
canvasHeight: 1920
question:
entity:
id: 123
text: Ask me anything!
createdAt: 2025-01-01T01:01:01+00:00
type: question
positions:
zIndex: 7
x: null
y: null
top: 30
left: 25
width: 257
height: 160
angle: 0
color: "#FF51DC"
texts:
- text: New drop today!
type: text
users: []
scale: 1
textAlign: left
textWidth: 181
textHeight: 41.2
color: "#FFFFFF"
bgColor: "#FF51DC"
fontFamily: ShantellSans
fontStyle: null
fontWeight: 400
top: 60
left: 25
angle: 0
fontSize: 24px
zIndex: 8
- text: @username
type: mention
users:
- view: stv
id: 124
name: Example Creator
username: username
isVerified: true
isDeleted: false
isActive: true
avatar: null
avatarThumbs: null
scale: 1
textAlign: left
textWidth: 145
textHeight: 37
color: "#0091EA"
bgColor: "#ffffff"
fontFamily: Roboto
fontStyle: null
fontWeight: 500
top: 48
left: 25
angle: 0
fontSize: 20px
zIndex: 9
viewersCount: 0
viewers: []
commentsCount: 0
canDelete: true
isHighlightCover: false
isLastInHighlight: false
tipsAmount: $0
tipsAmountRaw: 0
tipsCount: 0
likesCount: 0
releaseForms:
- id: 124
name: Example Creator
partnerSource: text
type: user
user:
view: tu
id: 124
name: Example Creator
username: username
isIdentityVerified: true
ivStatus: approved
isFromGuest: false
avatar: null
avatarThumbs: null
_meta:
_credits:
used: 1
balance: 1000999771
note: Always
_cache:
is_cached: false
note: Cache disabled for this endpoint
_rate_limits:
limit_minute: 5000
limit_day: null
remaining_minute: 4995
remaining_day: null
notice: We have decided to remove our daily rate limits. Please remove any
references to these in your integrations.
properties:
data:
type: object
properties:
id:
type: integer
example: 123
userId:
type: integer
example: 123
isReady:
type: boolean
example: false
hasPost:
type: boolean
example: false
isWatched:
type: boolean
example: false
media:
type: array
example:
- id: 123
type: photo
convertedToVideo: false
canView: true
hasError: false
createdAt: 2025-01-01T01:01:01+00:00
isReady: false
files:
full:
url: null
width: 0
height: 0
size: 0
sources: []
thumb: null
preview: null
squarePreview: null
duration: 0
hasCustomPreview: false
items:
type: object
properties:
id:
type: integer
example: 123
type:
type: string
example: photo
convertedToVideo:
type: boolean
example: false
canView:
type: boolean
example: true
hasError:
type: boolean
example: false
createdAt:
type: string
example: 2025-01-01T01:01:01+00:00
isReady:
type: boolean
example: false
files:
type: object
properties:
full:
type: object
properties:
url:
type: string
example: null
nullable: true
width:
type: integer
example: 0
height:
type: integer
example: 0
size:
type: integer
example: 0
sources:
type: array
example: []
thumb:
type: string
example: null
nullable: true
preview:
type: string
example: null
nullable: true
squarePreview:
type: string
example: null
nullable: true
duration:
type: integer
example: 0
hasCustomPreview:
type: boolean
example: false
createdAt:
type: string
example: 2025-01-01T01:01:01+00:00
canvasWidth:
type: integer
example: 1080
canvasHeight:
type: integer
example: 1920
question:
type: object
properties:
entity:
type: object
properties:
id:
type: integer
example: 123
text:
type: string
example: Ask me anything!
createdAt:
type: string
example: 2025-01-01T01:01:01+00:00
type:
type: string
example: question
positions:
type: object
properties:
zIndex:
type: integer
example: 7
x:
type: string
example: null
nullable: true
y:
type: string
example: null
nullable: true
top:
type: integer
example: 30
left:
type: integer
example: 25
width:
type: integer
example: 257
height:
type: integer
example: 160
angle:
type: integer
example: 0
color:
type: string
example: "#FF51DC"
texts:
type: array
example:
- text: New drop today!
type: text
users: []
scale: 1
textAlign: left
textWidth: 181
textHeight: 41.2
color: "#FFFFFF"
bgColor: "#FF51DC"
fontFamily: ShantellSans
fontStyle: null
fontWeight: 400
top: 60
left: 25
angle: 0
fontSize: 24px
zIndex: 8
- text: @username
type: mention
users:
- view: stv
id: 124
name: Example Creator
username: username
isVerified: true
isDeleted: false
isActive: true
avatar: null
avatarThumbs: null
scale: 1
textAlign: left
textWidth: 145
textHeight: 37
color: "#0091EA"
bgColor: "#ffffff"
fontFamily: Roboto
fontStyle: null
fontWeight: 500
top: 48
left: 25
angle: 0
fontSize: 20px
zIndex: 9
items:
type: object
properties:
text:
type: string
example: New drop today!
type:
type: string
example: text
users:
type: array
example: []
scale:
type: integer
example: 1
textAlign:
type: string
example: left
textWidth:
type: integer
example: 181
textHeight:
type: number
example: 41.2
color:
type: string
example: "#FFFFFF"
bgColor:
type: string
example: "#FF51DC"
fontFamily:
type: string
example: ShantellSans
fontStyle:
type: string
example: null
nullable: true
fontWeight:
type: integer
example: 400
top:
type: integer
example: 60
left:
type: integer
example: 25
angle:
type: integer
example: 0
fontSize:
type: string
example: 24px
zIndex:
type: integer
example: 8
viewersCount:
type: integer
example: 0
viewers:
type: array
example: []
commentsCount:
type: integer
example: 0
canDelete:
type: boolean
example: true
isHighlightCover:
type: boolean
example: false
isLastInHighlight:
type: boolean
example: false
tipsAmount:
type: string
example: $0
tipsAmountRaw:
type: integer
example: 0
tipsCount:
type: integer
example: 0
likesCount:
type: integer
example: 0
releaseForms:
type: array
example:
- id: 124
name: Example Creator
partnerSource: text
type: user
user:
view: tu
id: 124
name: Example Creator
username: username
isIdentityVerified: true
ivStatus: approved
isFromGuest: false
avatar: null
avatarThumbs: null
items:
type: object
properties:
id:
type: integer
example: 124
name:
type: string
example: Example Creator
partnerSource:
type: string
example: text
type:
type: string
example: user
user:
type: object
properties:
view:
type: string
example: tu
id:
type: integer
example: 124
name:
type: string
example: Example Creator
username:
type: string
example: username
isIdentityVerified:
type: boolean
example: true
ivStatus:
type: string
example: approved
isFromGuest:
type: boolean
example: false
avatar:
type: string
example: null
nullable: true
avatarThumbs:
type: string
example: null
nullable: true
_meta:
type: object
properties:
_credits:
type: object
properties:
used:
type: integer
example: 1
balance:
type: integer
example: 1000999771
note:
type: string
example: Always
_cache:
type: object
properties:
is_cached:
type: boolean
example: false
note:
type: string
example: Cache disabled for this endpoint
_rate_limits:
type: object
properties:
limit_minute:
type: integer
example: 5000
limit_day:
type: string
example: null
nullable: true
remaining_minute:
type: integer
example: 4995
remaining_day:
type: string
example: null
nullable: true
notice:
type: string
example: We have decided to remove our daily rate limits. Please remove any
references to these in your integrations.
tags:
- Stories
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mediaFiles:
type: array
description: Array of media file upload prefixed_ids, or OF vault media IDs.
example:
- ofapi_media_abc123
- 1234567890
items:
type: string
texts:
type: array
description: Text and @mention overlays.
example:
- []
items:
type: object
properties:
text:
type: string
description: The overlay text. For mentions this must be the `@username` to
mention (OnlyFans resolves the user and adds them to
the story's release forms).
example: New drop today!
type:
type: string
description: Overlay type. Default `text`.
example: text
enum:
- text
- mention
fontFamily:
type: string
description: "Font family. Families support specific weights only: Roboto
(400/500/700), PTMono (400), ShantellSans (400),
SofiaSans (400, renders uppercase), YanoneKaffeesatz
(700), RubikMedium (500), RubikBlack (700). Default
`Roboto`. Ignored for mentions (always Roboto 500)."
example: ShantellSans
enum:
- Roboto
- PTMono
- ShantellSans
- SofiaSans
- YanoneKaffeesatz
- RubikMedium
- RubikBlack
fontWeight:
type: integer
description: Font weight; must match the chosen family (see `fontFamily`).
example: 400
enum:
- 400
- 500
- 700
fontSize:
type: number
description: Font size in canvas px (8-100). The native editor uses 9-36.
Default `20`.
example: 24
color:
type: string
description: "Text color (hex). Defaults to the native editor behavior: white on
a colored background, black on a white background
(mentions: OnlyFans blue `#0091EA` on white)."
example: "#FFFFFF"
bgColor:
type: string
description: "Background color (hex, `#00000000` = transparent). Native editor
palette: #FFFFFF #000000 #69818C #FF51DC #FF4081
#FA3240 #FF8040 #FCA800 #70CF27 #00C864 #00B1CC
#2196F3 #7953F5 #A832BF. Default: transparent for
texts, white for mentions."
example: "#FF51DC"
textAlign:
type: string
description: Text alignment. Default `left`.
example: center
enum:
- left
- center
- right
left:
type: number
description: Horizontal position as a percentage of the canvas width (0-100).
Default `25`.
example: 30.5
top:
type: number
description: Vertical position as a percentage of the canvas height (0-100).
Defaults stagger each overlay below the previous one.
example: 60
angle:
type: number
description: Rotation in degrees. Default `0`.
example: 0
scale:
type: number
description: Scale factor. Default `1`.
example: 1
zIndex:
type: integer
description: Stacking order. Defaults to placement order.
example: 8
textWidth:
type: number
description: Rendered text box width in canvas px. Estimated automatically when
omitted.
example: 140
textHeight:
type: number
description: Rendered text box height in canvas px. Estimated automatically when
omitted.
example: 36
required:
- text
question:
type: object
description: Interactive question sticker viewers can answer.
example: []
properties:
text:
type: string
description: The question to ask.
example: Ask me anything!
color:
type: string
description: Sticker accent color (hex). Default `#FF51DC`.
example: "#FF51DC"
left:
type: number
description: Horizontal position as a percentage of the canvas width (0-100).
Default `25`.
example: 25
top:
type: number
description: Vertical position as a percentage of the canvas height (0-100).
Default `30`.
example: 30
width:
type: number
description: Sticker width in canvas px. Default `257`.
example: 257
height:
type: number
description: Sticker height in canvas px. Default `160`.
example: 160
canvasWidth:
type: integer
description: Canvas width overlay positions are relative to. Default `1080`.
example: 1080
canvasHeight:
type: integer
description: Canvas height overlay positions are relative to. Default `1920`.
example: 1920
required:
- mediaFiles
components:
securitySchemes:
default:
type: http
scheme: bearer
description: Get your API Key from OnlyFansAPI Console -
https://app.onlyfansapi.com/api-keys
````