Neynar studio API

openapi: 3.0.4
info:
  contact:
    email: team@neynar.com
    name: Neynar
    url: https://neynar.com/
  description: The Neynar API allows you to interact with the Farcaster protocol among other things. See the [Neynar docs](https://docs.neynar.com/reference) for more details.
  title: Neynar Action studio API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- name: studio
paths:
  /v2/studio/credit-drops/:
    get:
      description: Returns the most recent credit drop for the authenticated user. Returns the drop regardless of claimed/expired status.
      externalDocs:
        url: https://docs.neynar.com/reference/get-credit-drop
      operationId: get-credit-drop
      parameters:
      - description: Farcaster ID of the user
        in: query
        name: fid
        required: true
        schema:
          example: 3
          format: int32
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  allowance_expires_at:
                    description: 'Timestamp at which the drop stops contributing to the effective CU limit. Stamped by the credit-drop job at insert time (default: created_at + 24h).'
                    format: date-time
                    type: string
                  claimed:
                    description: Whether the credit drop has been claimed
                    type: boolean
                  created_at:
                    description: When the credit drop was generated
                    format: date-time
                    type: string
                  credits_remaining:
                    description: reward_amount - credits_used, clamped at 0. Spendable only until allowance_expires_at.
                    nullable: true
                    type: number
                  credits_used:
                    description: Portion of this drop already consumed against STUDIO CU usage (incremented by the CU sync). Forfeited at allowance_expires_at if unused.
                    type: number
                  expired:
                    description: Whether the credit drop's allowance window has closed (NOW() >= allowance_expires_at). Once true, the drop no longer contributes to the effective CU limit; any unused portion is forfeited.
                    type: boolean
                  percentile_score:
                    description: Percentile rank within 7-day global distribution
                    maximum: 1
                    minimum: 0
                    nullable: true
                    type: number
                  raw_score:
                    description: Raw quality score from 0 to 1
                    maximum: 1
                    minimum: 0
                    nullable: true
                    type: number
                  reward_amount:
                    description: Credit reward amount
                    nullable: true
                    type: number
                required:
                - created_at
                - raw_score
                - percentile_score
                - reward_amount
                - claimed
                - credits_used
                - credits_remaining
                - allowance_expires_at
                - expired
                type: object
          description: Success
        '402':
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                  message:
                    type: string
                required:
                - message
                - code
                type: object
          description: Payment Required
        '404':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                - message
                type: object
          description: Resource not found
      security:
      - ApiKeyAuth: []
      summary: Get most recent credit drop
      tags:
      - studio
  /v2/studio/credit-drops/claim:
    post:
      description: Claims the most recent credit drop for the authenticated user. The drop's allowance is surfaced dynamically until expires_at and does not mutate extra_credits. Only drops created within the past 24 hours can be claimed.
      externalDocs:
        url: https://docs.neynar.com/reference/claim-credit-drop
      operationId: claim-credit-drop
      requestBody:
        content:
          application/json:
            schema:
              properties:
                fid:
                  description: Farcaster ID of the user
                  example: 3
                  format: int32
                  minimum: 0
                  type: integer
              required:
              - fid
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  claimed:
                    enum:
                    - true
                    type: boolean
                  new_extra_credits:
                    description: New total extra credits balance
                    type: number
                  reward_amount:
                    description: Amount of credits added
                    type: number
                required:
                - claimed
                - reward_amount
                - new_extra_credits
                type: object
          description: Success
        '402':
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                  message:
                    type: string
                required:
                - message
                - code
                type: object
          description: Payment Required
        '404':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                - message
                type: object
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                - message
                type: object
          description: Conflict
        '410':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                - message
                type: object
          description: Gone
      security:
      - ApiKeyAuth: []
      summary: Claim credit drop
      tags:
      - studio
  /v2/studio/deployment/:
    delete:
      description: 'Deletes a specific miniapp generator deployment or all deployments for a FID. If deployment_id or name is provided, deletes single deployment. If only FID is provided, deletes all deployments for that FID. Requires API key authentication. Note: Studio CU is tracked based on LLM token usage, not per API call.'
      externalDocs:
        url: https://docs.neynar.com/reference/delete-deployment
      operationId: delete-deployment
      requestBody:
        content:
          application/json:
            schema:
              properties:
                deployment_id:
                  description: Deployment ID (UUID). If provided, deletes this specific deployment.
                  format: uuid
                  type: string
                fid:
                  description: Farcaster ID of the user
                  example: 3
                  format: int32
                  minimum: 0
                  type: integer
                name:
                  description: Kubernetes deployment name. If not provided and deployment_id not provided, all deployments for the FID will be deleted
                  type: string
                namespace:
                  description: Optional Kubernetes namespace. If not provided, will query for the active namespace for the given FID.
                  type: string
              required:
              - fid
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  deletedCount:
                    type: number
                  success:
                    type: boolean
                required:
                - success
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Server Error
      security:
      - ApiKeyAuth: []
      summary: Delete deployment(s)
      tags:
      - studio
    get:
      description: 'Lists all miniapp generator deployments for a user. Requires API key authentication. Note: Studio CU is tracked based on LLM token usage, not per API call.'
      externalDocs:
        url: https://docs.neynar.com/reference/list-deployments
      operationId: list-deployments
      parameters:
      - description: Farcaster ID of the user. Required for non-admin users. Studio admins can omit to query all deployments.
        in: query
        name: fid
        schema:
          example: 3
          format: int32
          minimum: 0
          type: integer
      - description: Maximum number of deployments to return. Defaults to 50, max 1000.
        in: query
        name: limit
        schema:
          default: 50
          maximum: 1000
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Number of deployments to skip for pagination. Defaults to 0.
        in: query
        name: offset
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: Search string to filter deployments by name, display name, or FID.
        in: query
        name: query
        schema:
          type: string
      - description: Field to sort deployments by. Defaults to updated_at (most recently updated first).
        in: query
        name: sort_by
        schema:
          default: updated_at
          enum:
          - created_at
          - updated_at
          type: string
      - description: Include deleted deployments in the response. Defaults to false.
        in: query
        name: include_deleted
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  properties:
                    created_at:
                      description: Creation timestamp
                      format: date-time
                      type: string
                    deleted_at:
                      description: Deletion timestamp
                      format: date-time
                      nullable: true
                      type: string
                    dev_server_state:
                      description: 'Dev server process state: stopped, starting, running, crashed, or hung'
                      enum:
                      - stopped
                      - starting
                      - running
                      - crashed
                      - hung
                      type: string
                    display_name:
                      description: Display name for the project
                      type: string
                    generated_app_exists:
                      description: Whether a generated app exists in the deployment
                      type: boolean
                    generated_app_serving:
                      description: Whether the generated app is currently serving
                      type: boolean
                    github_url:
                      description: GitHub repository SSH URL
                      type: string
                    has_database:
                      description: Whether the deployment has a Neon database configured
                      type: boolean
                    id:
                      description: Deployment ID
                      type: string
                    is_ready:
                      description: Deployment is ready to serve app and accept prompts
                      type: boolean
                    name:
                      description: Kubernetes deployment name
                      type: string
                    namespace:
                      description: Kubernetes namespace
                      type: string
                    production_app_status:
                      description: Production app deployment status from Vercel
                      properties:
                        created_at:
                          description: Deployment creation timestamp (Unix ms)
                          type: number
                        deployment_state:
                          description: Deployment state (e.g., READY, BUILDING, ERROR)
                          type: string
                        deployment_url:
                          description: Vercel deployment URL
                          type: string
                        project_id:
                          description: Vercel project ID
                          type: string
                        target:
                          description: Deployment target (e.g., production, preview)
                          type: string
                      required:
                      - project_id
                      - deployment_url
                      - deployment_state
                      - created_at
                      type: object
                    updated_at:
                      description: Last update timestamp
                      format: date-time
                      nullable: true
                      type: string
                    url:
                      description: Public URL for the deployment
                      format: uri
                      type: string
                  required:
                  - id
                  - deleted_at
                  - updated_at
                  - created_at
                  - namespace
                  - name
                  - is_ready
                  - generated_app_exists
                  - generated_app_serving
                  type: object
                type: array
          description: Success
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Server Error
      security:
      - ApiKeyAuth: []
      summary: List deployments
      tags:
      - studio
    post:
      description: 'Creates and deploys an instance of the miniapp generator for a user. Requires authentication via API key in the request header. Note: Studio CU is tracked based on LLM token usage, not per API call.'
      externalDocs:
        url: https://docs.neynar.com/reference/create-deployment
      operationId: create-deployment
      requestBody:
        content:
          application/json:
            schema:
              properties:
                display_name:
                  description: Display name for the deployment
                  type: string
                env:
                  additionalProperties:
                    type: string
                  description: Environment variables for the deployment
                  type: object
                fid:
                  description: Farcaster ID of the user
                  example: 3
                  format: int32
                  minimum: 0
                  type: integer
              required:
              - fid
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    description: Creation timestamp
                    format: date-time
                    type: string
                  deleted_at:
                    description: Deletion timestamp
                    format: date-time
                    nullable: true
                    type: string
                  dev_server_state:
                    description: 'Dev server process state: stopped, starting, running, crashed, or hung'
                    enum:
                    - stopped
                    - starting
                    - running
                    - crashed
                    - hung
                    type: string
                  display_name:
                    description: Display name for the project
                    type: string
                  generated_app_exists:
                    description: Whether a generated app exists in the deployment
                    type: boolean
                  generated_app_serving:
                    description: Whether the generated app is currently serving
                    type: boolean
                  github_url:
                    description: GitHub repository SSH URL
                    type: string
                  has_database:
                    description: Whether the deployment has a Neon database configured
                    type: boolean
                  id:
                    description: Deployment ID
                    type: string
                  is_ready:
                    description: Deployment is ready to serve app and accept prompts
                    type: boolean
                  name:
                    description: Kubernetes deployment name
                    type: string
                  namespace:
                    description: Kubernetes namespace
                    type: string
                  production_app_status:
                    description: Production app deployment status from Vercel
                    properties:
                      created_at:
                        description: Deployment creation timestamp (Unix ms)
                        type: number
                      deployment_state:
                        description: Deployment state (e.g., READY, BUILDING, ERROR)
                        type: string
                      deployment_url:
                        description: Vercel deployment URL
                        type: string
                      project_id:
                        description: Vercel project ID
                        type: string
                      target:
                        description: Deployment target (e.g., production, preview)
                        type: string
                    required:
                    - project_id
                    - deployment_url
                    - deployment_state
                    - created_at
                    type: object
                  updated_at:
                    description: Last update timestamp
                    format: date-time
                    nullable: true
                    type: string
                  url:
                    description: Public URL for the deployment
                    format: uri
                    type: string
                required:
                - id
                - deleted_at
                - updated_at
                - created_at
                - namespace
                - name
                - is_ready
                - generated_app_exists
                - generated_app_serving
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Server Error
      security:
      - ApiKeyAuth: []
      summary: Create a miniapp generator deployment
      tags:
      - studio
  /v2/studio/deployment/account-association:
    get:
      description: Retrieves the account-association.json file from a miniapp deployment, which contains the JFS-signed domain association. Requires API key authentication.
      externalDocs:
        url: https://docs.neynar.com/reference/get-account-association
      operationId: get-account-association
      parameters:
      - description: Deployment ID
        in: query
        name: deployment_id
        schema:
          format: uuid
          type: string
      - description: Kubernetes namespace name
        in: query
        name: namespace
        schema:
          type: string
      - description: Kubernetes deployment name
        in: query
        name: name
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  header:
                    description: Base64URL encoded JFS header
                    type: string
                  payload:
                    description: Base64URL encoded JFS payload
                    type: string
                  signature:
                    description: Base64URL encoded JFS signature
                    type: string
                required:
                - header
                - payload
                - signature
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Server Error
      security:
      - ApiKeyAuth: []
      summary: Get account association of a miniapp
      tags:
      - studio
    post:
      description: 'Associates a generated miniapp with a Farcaster account using a JFS-signed domain association. Requires API key authentication. Note: Studio CU is tracked based on LLM token usage, not per API call.'
      externalDocs:
        url: https://docs.neynar.com/reference/associate-deployment
      operationId: associate-deployment
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account_association:
                  description: Signed domain association linking this deployment to a Farcaster account
                  properties:
                    header:
                      description: Base64URL encoded JFS header
                      type: string
                    payload:
                      description: Base64URL encoded JFS payload
                      type: string
                    signature:
                      description: Base64URL encoded JFS signature
                      type: string
                  required:
                  - header
                  - payload
                  - signature
                  type: object
                deployment_id:
                  description: Deployment ID (UUID). Required if name not provided.
                  format: uuid
                  type: string
                fid:
                  description: Farcaster ID of the user; if not provided, namespace must be provided
                  example: 3
                  format: int32
                  minimum: 0
                  type: integer
                name:
                  description: Kubernetes deployment name. Required if deployment_id not provided.
                  type: string
                namespace:
                  description: Optional Kubernetes namespace. If not provided, will query for the active namespace for the given FID.
                  type: string
              required:
              - account_association
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Status message from the miniapp generator
                    type: string
                  success:
                    type: boolean
                required:
                - success
                - message
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Server Error
      security:
      - ApiKeyAuth: []
      summary: Set account association
      tags:
      - studio
  /v2/studio/deployment/build:
    post:
      description: 'Runs Next.js build process for the generated app. If build fails, automatically calls a build-fixer agent to resolve errors. Streams build output and agent responses via Server-Sent Events. Requires API key authentication. Note: Studio CU is tracked based on LLM token usage, not per API call.'
      externalDocs:
        url: https://docs.neynar.com/reference/build
      operationId: build
      requestBody:
        content:
          application/json:
            schema:
              properties:
                build_type:
                  default: vercel
                  description: Build tool to use. "vercel" runs vercel build for production deployment. "npm" runs npm run build for dev server recovery.
                  enum:
                  - npm
                  - vercel
                  type: string
                deployment_id:
                  description: Deployment ID
                  format: uuid
                  type: string
                name:
                  description: Kubernetes deployment name
                  type: string
                namespace:
                  description: Kubernetes namespace
                  type: string
              type: object
        required: true
      responses:
        '200':
          description: Success
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                required:
                - error
                type: object
          description: Server Error
      security:
      - ApiKeyAuth: []
      summary: Build generated app with automatic error fixing
      tags:
      - studio
  /v2/studio/deployment/by-name-and-fid:
    get:
      description: 'Fetches info about a miniapp generator deployment by its deployment_id or name and creator''s Farcaster ID. Requires API key authentication. Note: Studio CU is tracked based on LLM token usage, not per API call.'
      externalDocs:
        url: https://docs.neynar.com/reference/get-deployment
      operationId: get-deployment
      parameters:
      - description: Deployment ID (UUID). Required if name not provided.
        in: query
        name: deployment_id
        schema:
          format: uuid
          type: string
      - description: Farcaster ID of the user; if not provided, namespace must be provided
        in: query
        name: fid
        schema:
          example: 3
          format: int32
          minimum: 0
          type: integer
      - description: Kubernetes deployment name. Required if deployment_id not provided.
        in: query
        name: name
        schema:
          type: string
      - description: Optional Kubernetes namespace. If not provided, will query for the active namespace for the given FID.
        in: query
        name: namespace
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    description: Creation timestamp
                    format: date-time
                    type: string
                  deleted_at:
                    description: Deletion timestamp
                    format: date-time
                    nullable: true
                    type: string
                  dev_server_state:
                    description: 'Dev server process state: stopped, starting, running, crashed, or hung'
                    enum:
                    - stopped
                    - starting
                    - running
                    - crashed
                    - hung
                    type: string
                  display_name:
                    description: Display name for the project
                    type: string
    

# --- truncated at 32 KB (139 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/api-evangelist-neynar/refs/heads/main/openapi/neynar-studio-api-openapi.yml