# Create a gist

From **GitHub v3 REST API**.

`POST /gists`

Allows you to add a new gist with one or more files.

**Note:** Don't name your files "gistfile" with a numerical suffix. This is the format of the automatic naming scheme that Gist uses internally.

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{"properties":{"description":{"description":"Description of the gist","example":"Example Ruby script","type":"string"},"files":{"additionalProperties":{"properties":{"content":{"description":"Content of the file","type":"string"}},"required":["content"],"type":"object"},"description":"Names and content for the files that make up the gist","example":{"hello.rb":{"content":"puts \"Hello, World!\""}},"type":"object"},"public":{"oneOf":[{"default":false,"description":"Flag indicating whether the gist is public","example":true,"type":"boolean"},{"default":"false","enum":["true","false"],"example":"true","type":"string"}]}},"required":["files"],"type":"object"}
```

## Responses

### `201`

Response

#### Headers

##### `Location`

- Type: `string`

- Example: `https://api.github.com/gists/aa5a315d61ae9438b18d`

### `application/json`

- Type: `object`

Gist Simple

```json
{
  "comments": 0,
  "comments_url": "https://api.github.com/gists/aa5a315d61ae9438b18d/comments/",
  "commits_url": "https://api.github.com/gists/aa5a315d61ae9438b18d/commits",
  "created_at": "2010-04-14T02:15:15Z",
  "description": "Hello World Examples",
  "forks_url": "https://api.github.com/gists/aa5a315d61ae9438b18d/forks",
  "git_pull_url": "https://gist.github.com/aa5a315d61ae9438b18d.git",
  "git_push_url": "https://gist.github.com/aa5a315d61ae9438b18d.git",
  "html_url": "https://gist.github.com/aa5a315d61ae9438b18d",
  "id": "aa5a315d61ae9438b18d",
  "node_id": "MDQ6R2lzdGFhNWEzMTVkNjFhZTk0MzhiMThk",
  "updated_at": "2011-06-20T11:34:15Z",
  "url": "https://api.github.com/gists/aa5a315d61ae9438b18d"
}
```

```json
{"description":"Gist Simple","properties":{"comments":{"type":"integer"},"comments_url":{"type":"string"},"commits_url":{"type":"string"},"created_at":{"type":"string"},"description":{"nullable":true,"type":"string"},"files":{"additionalProperties":{"nullable":true,"properties":{"content":{"type":"string"},"filename":{"type":"string"},"language":{"type":"string"},"raw_url":{"type":"string"},"size":{"type":"integer"},"truncated":{"type":"boolean"},"type":{"type":"string"}},"type":"object"},"type":"object"},"fork_of":{"description":"Gist","nullable":true,"properties":{"comments":{"type":"integer"},"comments_url":{"format":"uri","type":"string"},"commits_url":{"format":"uri","type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"nullable":true,"type":"string"},"files":{"additionalProperties":{"properties":{"filename":{"type":"string"},"language":{"type":"string"},"raw_url":{"type":"string"},"size":{"type":"integer"},"type":{"type":"string"}},"type":"object"},"type":"object"},"forks":{"items":{},"type":"array"},"forks_url":{"format":"uri","type":"string"},"git_pull_url":{"format":"uri","type":"string"},"git_push_url":{"format":"uri","type":"string"},"history":{"items":{},"type":"array"},"html_url":{"format":"uri","type":"string"},"id":{"type":"string"},"node_id":{"type":"string"},"owner":{"$ref":"#/components/schemas/nullable-simple-user"},"public":{"type":"boolean"},"truncated":{"type":"boolean"},"updated_at":{"format":"date-time","type":"string"},"url":{"format":"uri","type":"string"},"user":{"$ref":"#/components/schemas/nullable-simple-user"}},"required":["id","node_id","url","forks_url","commits_url","git_pull_url","git_push_url","html_url","comments_url","public","description","comments","user","files","created_at","updated_at"],"title":"Gist","type":"object"},"forks":{"deprecated":true,"items":{"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"updated_at":{"format":"date-time","type":"string"},"url":{"format":"uri","type":"string"},"user":{"$ref":"#/components/schemas/public-user"}},"type":"object"},"nullable":true,"type":"array"},"forks_url":{"type":"string"},"git_pull_url":{"type":"string"},"git_push_url":{"type":"string"},"history":{"deprecated":true,"items":{"$ref":"#/components/schemas/gist-history"},"nullable":true,"type":"array"},"html_url":{"type":"string"},"id":{"type":"string"},"node_id":{"type":"string"},"owner":{"$ref":"#/components/schemas/simple-user"},"public":{"type":"boolean"},"truncated":{"type":"boolean"},"updated_at":{"type":"string"},"url":{"type":"string"},"user":{"nullable":true,"type":"string"}},"title":"Gist Simple","type":"object"}
```

### `304`

Not modified

### `403`

Forbidden

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `404`

Resource not found

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

```shell
curl --request POST \
  --url {protocol}://{hostname}/api/v3/gists \
  --header 'content-type: application/json' \
  --data '{
  "description": "string",
  "files": {},
  "public": "string"
}'
```