Create a gist

POST/gists

Creates a gist owned by the authenticated caller.

Files are provided as an object keyed by filename. Entries without a content value are dropped; at least one file with content is required. When title is omitted it is derived from the first filename.

Request

Headers

Name	Type	Scopes
Authorizationrequired	string	gist:write

Body parameters

GistCreateRequestrequiredapplication/json

Field	Type	Description
titleoptional	string	Optional; derived from the first filename when omitted.
descriptionoptional	string
visibilityoptional	string: public | unlisted | private
expireoptional	string: never | 1hour | 12hours | 1day | 7days | 15days	When set, the gist is automatically deleted after the given delay.
expires_atoptional	string <date-time>	A custom expiration date (RFC3339). When set it takes precedence over expire.
filesrequired	map<string, GistCreateFileInput>	Files keyed by filename. At least one entry must have content.
↳contentoptional	string	File body. Entries without content are dropped.

Responses

Status	Body	Description
201	Gist	The created gist.
	Headers:Location
401	Error	Missing or invalid credentials.
403	Error	The token lacks the required scope or permission.
422	Error	The request body failed validation.

Request

curl -X POST \
  --url "https://opengist.example.com/api/gists" \
  -H "Authorization: Bearer og_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "string",
  "description": "string",
  "visibility": "public",
  "expire": "never",
  "expires_at": "2024-01-01T00:00:00Z",
  "files": {
    "<key>": {
      "content": "string"
    }
  }
}'

Response 201

{
  "id": "string",
  "slug_url": "string",
  "owner": {
    "id": 1,
    "login": "string",
    "username": "string",
    "avatar_url": "https://opengist.example/...",
    "type": "string",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "title": "string",
  "html_url": "https://opengist.example/...",
  "description": "string",
  "public": true,
  "visibility": "public",
  "like_count": 1,
  "fork_count": 1,
  "clone_url": "https://opengist.example/...",
  "ssh_url": "string",
  "topics": [
    "string"
  ],
  "archived": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "expires_at": "2024-01-01T00:00:00Z",
  "fork_of": {
    "id": "string",
    "slug_url": "string",
    "owner": {
      "id": 1,
      "login": "string",
      "username": "string",
      "avatar_url": "https://opengist.example/...",
      "type": "string",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "title": "string",
    "html_url": "https://opengist.example/...",
    "description": "string",
    "public": true,
    "visibility": "public",
    "like_count": 1,
    "fork_count": 1,
    "clone_url": "https://opengist.example/...",
    "ssh_url": "string",
    "topics": [
      "string"
    ],
    "archived": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "expires_at": "2024-01-01T00:00:00Z"
  },
  "forks": [
    {
      "id": "string",
      "slug_url": "string",
      "owner": {
        "id": 1,
        "login": "string",
        "username": "string",
        "avatar_url": "https://opengist.example/...",
        "type": "string",
        "created_at": "2024-01-01T00:00:00Z"
      },
      "title": "string",
      "html_url": "https://opengist.example/...",
      "description": "string",
      "public": true,
      "visibility": "public",
      "like_count": 1,
      "fork_count": 1,
      "clone_url": "https://opengist.example/...",
      "ssh_url": "string",
      "topics": [
        "string"
      ],
      "archived": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "expires_at": "2024-01-01T00:00:00Z"
    }
  ],
  "files": {
    "<key>": {
      "filename": "string",
      "type": "string",
      "language": "string",
      "size": 1,
      "truncated": true,
      "content": "string",
      "encoding": "string"
    }
  },
  "commits": [
    {
      "version": "string",
      "author": {
        "name": "string",
        "email": "string"
      },
      "user": {
        "id": 1,
        "login": "string",
        "username": "string",
        "avatar_url": "https://opengist.example/...",
        "type": "string",
        "created_at": "2024-01-01T00:00:00Z"
      },
      "change_status": {
        "files_changed": 1,
        "additions": 1,
        "deletions": 1,
        "total": 1
      },
      "committed_at": "2024-01-01T00:00:00Z"
    }
  ],
  "truncated": true
}