Govir API

openapi: 3.1.0
info:
  title: Govir API
  version: '2026-11-10'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-10: 28 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Govir has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 25
    pages-with-code: 1
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-10'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://govir.app/docs/api
paths:
  /accounts:
    get:
      operationId: get_accounts
      tags:
      - Accounts
      summary: the connected accounts.
      x-source: https://govir.app/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountsResponse'
      x-evidence:
        kind: documentation
  /accounts/{id}/metrics:
    get:
      operationId: get_accounts_id_metrics
      tags:
      - Accounts
      summary: 'GET /accounts/{id}/metrics (read): an account''s overview for a period: posts, views, likes, replies, reposts and quotes, interactions,
        engagement rate and link clicks.'
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
      - name: to
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /accounts/{id}/metrics/posts:
    get:
      operationId: get_accounts_id_metrics_posts
      tags:
      - Accounts
      summary: 'GET /accounts/{id}/metrics/posts (read): the account''s posts by what they gained in the period.'
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
      - name: to
        in: query
        required: false
        schema:
          type: string
      - name: sort
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/me:
    get:
      operationId: get_api_v1_me
      tags:
      - Api
      summary: GET /api/v1/me
      x-source: https://govir.app/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://govir.app/api/v1/me  -H \"Authorization: Bearer gvr_live_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY\"\n A key in\
          \ the URL is refused ( 400 ), so it doesn't end up in logs. \n Scopes \n read : accounts, posts and analytics. \n write : drafts, media,\
          \ scheduling and unscheduling. \n publish : publishing right away. It also needs Allow publishing right away to be on in Settings →\
          \ API . Without it,"
  /api/v1/media/from-url:
    get:
      operationId: get_api_v1_media_from_url
      tags:
      - Api
      summary: 'POST /media/from-url (write): Govir fetches the file at a public http or https link and prepares it like an upload.'
      description: Creates a media object by downloading a file from a public URL.
      x-source: https://govir.app/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1MediaFromUrlResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_media_from_url
      tags:
      - Api
      summary: POST /api/v1/media/from-url
      x-source: https://govir.app/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1MediaFromUrlRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1MediaFromUrlResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://govir.app/api/v1/media/from-url  -H \"Authorization: Bearer $GOVIR_API_KEY\"  -H \"Content-Type: application/json\"\
          \  -d '{ \"url\": \"https://example.com/photos/harbour.jpg\" }'\n {\n \"id\": \"…\",\n \"kind\": \"image\",\n \"status\": \"ready\"\
          ,\n \"error_code\": null,\n \"url\": \"https://…\",\n \"mime\": \"image/jpeg\",\n \"size\": 184211,\n \"width\": 1440,\n \"height\"\
          : 1080,\n \"duration_ms\": null\n}\n POST /media/upload-links "
  /api/v1/posts:
    get:
      operationId: get_api_v1_posts
      tags:
      - Api
      summary: 'Posts (read): posts, newest first.'
      description: Returns a list of posts ordered newest first, with optional filtering and pagination.
      x-source: https://govir.app/docs/api
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: Filter by post status (draft, scheduled, publishing, published, failed, …).
      - name: account_id
        in: query
        required: false
        schema:
          type: string
        description: Filter by the account ID.
      - name: from
        in: query
        required: false
        schema:
          type: string
        description: ISO time to filter posts from (inclusive).
      - name: to
        in: query
        required: false
        schema:
          type: string
        description: ISO time to filter posts to (inclusive).
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: Number of items per page (1–100, default 25).
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Cursor for pagination (use next_cursor from previous response).
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1PostsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_posts
      tags:
      - Api
      summary: POST /api/v1/posts
      x-source: https://govir.app/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1PostsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://govir.app/api/v1/posts  -H \"Authorization: Bearer $GOVIR_KEY\"  -H \"Content-Type: application/json\"  -H \"Idempotency-Key:\
          \ 6f1c2a7e-0d6b-4c55-9c1e-2b1f0e3b8a10\"  -d '{\n \"account_ids\": [\"…\"],\n \"parts\": [\n { \"text\": \"Three things I learned this\
          \ week \U0001F9F5\", \"media\": [{ \"id\": \"…\", \"alt_text\": \"A chart\" }] },\n { \"text\": \"1. Write every day.\" }\n ],\n \"\
          topic\": \"Writing\"\n }'\n Fields: account_ids (r"
  /gifs:
    get:
      operationId: get_gifs
      tags:
      - Gifs
      summary: 'GET /gifs (write): GIPHY GIFs to attach, trending or a search with q (up to 50 characters).'
      x-source: https://govir.app/docs/api
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /me:
    get:
      operationId: get_me
      tags:
      - Me
      summary: the key's workspace, plan and scopes, and whether publishing right away is allowed.
      x-source: https://govir.app/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMeResponse'
      x-evidence:
        kind: documentation
  /media:
    get:
      operationId: get_media
      tags:
      - Media
      summary: 'GET /media (write): images and videos already in your workspace, newest first.'
      x-source: https://govir.app/docs/api
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_media
      tags:
      - Media
      summary: initiate a file upload.
      x-source: https://govir.app/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMediaRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMediaResponse'
      x-evidence:
        kind: documentation
  /media/from-url:
    post:
      operationId: post_media_from_url
      tags:
      - Media
      summary: 'POST /media/from-url (write): Govir fetches the file at a public http or https link and prepares it like an upload.'
      x-source: https://govir.app/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMediaFromUrlRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMediaFromUrlResponse'
      x-evidence:
        kind: documentation
  /media/stock:
    post:
      operationId: post_media_stock
      tags:
      - Media
      summary: POST /media/stock (write) brings the chosen one into your media.
      x-source: https://govir.app/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMediaStockRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /media/upload-links:
    post:
      operationId: post_media_upload_links
      tags:
      - Media
      summary: 'POST /media/upload-links (write): a one-time page where you add files from your device.'
      x-source: https://govir.app/docs/api
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMediaUploadLinksResponse'
      x-evidence:
        kind: documentation
  /media/upload-links/{id}:
    get:
      operationId: get_media_upload_links_id
      tags:
      - Media
      summary: 'GET /media/upload-links/{id} returns status: "done" and the files in media.'
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMediaUploadLinksIdResponse'
      x-evidence:
        kind: documentation
  /media/{id}:
    get:
      operationId: get_media_id
      tags:
      - Media
      summary: Images are ready at once; videos are processed, so follow them with GET /media/{id} until status is ready.
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /media/{id}/complete:
    post:
      operationId: post_media_id_complete
      tags:
      - Media
      summary: finalize an upload after the file bytes have been sent.
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /posts:
    get:
      operationId: get_posts
      tags:
      - Posts
      summary: posts, newest first.
      x-source: https://govir.app/docs/api
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: filter by status
      - name: account_id
        in: query
        required: false
        schema:
          type: string
        description: filter by account
      - name: from
        in: query
        required: false
        schema:
          type: string
        description: ISO time start
      - name: to
        in: query
        required: false
        schema:
          type: string
        description: ISO time end
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: 1‑100, default 25
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: pagination cursor
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_posts
      tags:
      - Posts
      summary: a new draft.
      x-source: https://govir.app/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostPostsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPostsResponse'
      x-evidence:
        kind: documentation
  /posts/{id}:
    delete:
      operationId: delete_posts_id
      tags:
      - Posts
      summary: delete a draft or a scheduled post.
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_posts_id
      tags:
      - Posts
      summary: one post with its parts and media.
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPostsIdResponse'
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_posts_id
      tags:
      - Posts
      summary: change a draft.
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchPostsIdRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /posts/{id}/metrics:
    get:
      operationId: get_posts_id_metrics
      tags:
      - Posts
      summary: 'GET /posts/{id}/metrics (read): a published post''s totals and how they grew (history, with hours since publishing).'
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /posts/{id}/publish:
    post:
      operationId: post_posts_id_publish
      tags:
      - Posts
      summary: publish now.
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostPostsIdPublishRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /posts/{id}/schedule:
    post:
      operationId: post_posts_id_schedule
      tags:
      - Posts
      summary: schedule the post at a time, or in the next free slot of your queue.
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostPostsIdScheduleRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /posts/{id}/unschedule:
    post:
      operationId: post_posts_id_unschedule
      tags:
      - Posts
      summary: back to drafts.
      x-source: https://govir.app/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stock-photos:
    get:
      operationId: get_stock_photos
      tags:
      - Stock Photos
      summary: 'GET /stock-photos (write): free photos from Pexels and Pixabay.'
      x-source: https://govir.app/docs/api
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
      - name: provider
        in: query
        required: false
        schema:
          type: string
      - name: type
        in: query
        required: false
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    GetAccountsResponse:
      type: object
      properties:
        data:
          type: array
          description: list of account objects
    GetApiV1MediaFromUrlResponse:
      type: object
      properties:
        id:
          type: string
          description: Media identifier.
        kind:
          type: string
          description: Type of media (e.g., "image").
        status:
          type: string
          description: Current status (e.g., "ready").
        error_code:
          type: string
          description: Error code if processing failed.
        url:
          type: string
          description: URL to access the media.
        mime:
          type: string
          description: MIME type of the media.
        size:
          type: integer
          description: Size in bytes.
        width:
          type: integer
          description: Width in pixels (for images).
        height:
          type: integer
          description: Height in pixels (for images).
        duration_ms:
          type: integer
          description: Duration in milliseconds (for videos).
    PostApiV1MediaFromUrlRequest:
      type: object
      properties:
        url:
          type: string
    PostApiV1MediaFromUrlResponse:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        status:
          type: string
        expires_at:
          type: string
          format: date-time
        media:
          type: array
          items: {}
    GetApiV1PostsResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of post objects.
        next_cursor:
          type: string
          description: Cursor for the next page, if more results exist.
    PostApiV1PostsRequest:
      type: object
      properties:
        account_ids:
          type: array
          items:
            type: string
        parts:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              media:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    alt_text:
                      type: string
        topic:
          type: string
    GetMeResponse:
      type: object
      properties:
        workspace:
          type: object
          description: contains id and plan
        key:
          type: object
          description: contains prefix and scopes
        publish_enabled:
          type: boolean
          description: whether publishing right away is allowed
    PostMediaRequest:
      type: object
      properties:
        mime:
          type: string
        size:
          type: integer
      required:
      - mime
      - size
    PostMediaResponse:
      type: object
      properties:
        id:
          type: string
        upload:
          type: object
          description: method, url and headers for the PUT
    PostMediaFromUrlRequest:
      type: object
      properties:
        url:
          type: string
          description: Public http or https link to the file
      required:
      - url
    PostMediaFromUrlResponse:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
        status:
          type: string
        url:
          type: string
        mime:
          type: string
        size:
          type: integer
        width:
          type: integer
        height:
          type: integer
        duration_ms:
          type: integer
    PostMediaStockRequest:
      type: object
      properties:
        provider:
          type: string
        id:
          type: string
      required:
      - provider
      - id
    PostMediaUploadLinksResponse:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        status:
          type: string
        expires_at:
          type: string
        media:
          type: array
    GetMediaUploadLinksIdResponse:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        status:
          type: string
        expires_at:
          type: string
        media:
          type: array
    PostPostsRequest:
      type: object
      properties:
        account_ids:
          type: array
          description: target accounts
        text:
          type: string
          description: single‑post text
        parts:
          type: array
          description: thread parts
        topic:
          type: string
        reply_control:
          type: string
        part_numbers:
          type: string
        quote_post_id:
          type: string
        ghost:
          type: boolean
      required:
      - account_ids
    PostPostsResponse:
      type: object
      properties:
        group_id:
          type: string
        posts:
          type: array
    GetPostsIdResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        account_id:
          type: string
        group_id:
          type: string
        scheduled_at:
          type: string
        published_at:
          type: string
        permalink:
          type: string
        topic:
          type: string
        parts:
          type: array
          description: list of part objects
    PatchPostsIdRequest:
      type: object
      properties:
        account_ids:
          type: array
        text:
          type: string
        parts:
          type: array
        topic:
          type: string
        reply_control:
          type: string
        part_numbers:
          type: string
        quote_post_id:
          type: string
        ghost:
          type: boolean
    PostPostsIdPublishRequest:
      type: object
      properties:
        acknowledge_warnings:
          type: boolean
    PostPostsIdScheduleRequest:
      type: object
      properties:
        at:
          type: string
          description: ISO time with offset
        queue:
          type: boolean
          description: schedule in next free slot
        acknowledge_warnings:
          type: boolean
          description: bypass safeguards warnings
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Accounts
- name: Api
- name: Gifs
- name: Me
- name: Media
- name: Posts
- name: Stock Photos