<commit_before>FORMAT: 1A
HOST: https://api.thegrid.io/

# The Grid API

# Group Long-running jobs

Several actions in the API takes a significant time.
Current examples include POST /share, /publish and /unpublish.
Performing such an action returns a Location header with a Job URL.

## Job details [/job/{id}]

### Retriving job details [GET]

+ Parameters
  + id (required, string) - Job UUID

+ Response 200 (application/json)

  + Body
      ```
      <!-- include(examples/job-share-completed.json) -->
      ```

## Jobs [/job]

### Listing current jobs [GET]

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/job-share-completed.json) -->
      ]
      ```

# Group Newsfeed

## User's newsfeed [/updates{?offset,limit,measurements}]

### Fetch user's latest newsfeed [GET]

+ Parameters
  + offset (number) - Offset to use for pagination
  + limit (number) - Limit to use for pagination
  + measurements (string) - Selectively get only certain measurements

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/item-valid-minimal-item.json) -->
      ]
      ```

# Group Site Management

## Site information [/site]

### List user websites [GET]

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/site-minimal.json) -->
      ]
      ```

### Create a website [POST]

+ Request (application/json)

  **Note:** the repository must be in `the-domains` organization. The repository name can later be used for sharing content to the newly-created site.

  + Body

      ```
      <!-- include(examples/site-without-owner.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

+ Response 201

  Site was successfully created

  + Headers

            Location: /site/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

+ Response 422

  Missing site information

  + Body

## User website [/site/{id}]

+ Parameters
  + id (required, string) - Site UUID

### Get website details [GET]

+ Response 200 (application/json)

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

### Update website details [PUT]

+ Request (application/json)

  + Body

      ```
      <!-- include(examples/site-with-config.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

+ Response 200 (application/json)

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

### Delete website [DELETE]

+ Response 200

## Site DNS status [/site/{id}/dns]

+ Parameters
  + id (required, string) - Site UUID

### Check website DNS status [POST]

+ Response 200 (application/json)

  + Body 

       { "valid": true }

## Website discovery [/site/discover{?url}]

### Match URL to a website [GET]

+ Parameters
  + url (required, string) - URL of the website

+ Response 302

  + Headers

            Location: /site/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

+ Response 409

  Grid site belonging to another user was found at the URL

+ Response 404

  No Grid site was found for the URL

  + Body

# Group Content Management

## Share [/share]

### Sharing content [POST]

Users can share content to The Grid. The shared items will be normalized, analyzed and made available via the item API.
Sharing creates a Job, whos progress can be monitored using the /job API.

There are typically three different things you can be sharing:

* Full article pages: share with URL
* HTML fragments: selection or img tag. Share with content, type text/html and with the URL of the originating page
* Uploaded files: image, word document, HTML file, Markdown file, etc. Share with multi-part upload, URL and MIME type needed

Note that publishing an item to a website is a separate step. See /publish

+ Request with JSON payload (application/json)

  + Body

      ```
      <!-- include(examples/share-url-only.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/share.json) -->
      ```


+ Request with file upload (multipart/form-data)

  For images and other files the content is a file sent via multipart/form-data. If there is no relevant URL for the content, it is a good idea to generate a UUID URI.

  ```
  formData = new FormData()
  formData.append 'url', 'content://'
  formData.append 'type', file.type
  formData.append 'content', file
  ```

  + Body

+ Response 202

  Sharing was successful and will be processed.

  + Headers

            Location: /job/b8838e11-1d97-4799-85d8-1aafec52e927

  + Body

+ Response 422

  Missing required parameters

  + Body

+ Response 403

  Not allowed to share to the specified website

  + Body

## Random content [/share/random{?category,number}]<commit_msg>Remove docs for deprecated /share uploading<commit_after>FORMAT: 1A
HOST: https://api.thegrid.io/

# The Grid API

# Group Long-running jobs

Several actions in the API takes a significant time.
Current examples include POST /share, /publish and /unpublish.
Performing such an action returns a Location header with a Job URL.

## Job details [/job/{id}]

### Retriving job details [GET]

+ Parameters
  + id (required, string) - Job UUID

+ Response 200 (application/json)

  + Body
      ```
      <!-- include(examples/job-share-completed.json) -->
      ```

## Jobs [/job]

### Listing current jobs [GET]

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/job-share-completed.json) -->
      ]
      ```

# Group Newsfeed

## User's newsfeed [/updates{?offset,limit,measurements}]

### Fetch user's latest newsfeed [GET]

+ Parameters
  + offset (number) - Offset to use for pagination
  + limit (number) - Limit to use for pagination
  + measurements (string) - Selectively get only certain measurements

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/item-valid-minimal-item.json) -->
      ]
      ```

# Group Site Management

## Site information [/site]

### List user websites [GET]

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/site-minimal.json) -->
      ]
      ```

### Create a website [POST]

+ Request (application/json)

  **Note:** the repository must be in `the-domains` organization. The repository name can later be used for sharing content to the newly-created site.

  + Body

      ```
      <!-- include(examples/site-without-owner.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

+ Response 201

  Site was successfully created

  + Headers

            Location: /site/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

+ Response 422

  Missing site information

  + Body

## User website [/site/{id}]

+ Parameters
  + id (required, string) - Site UUID

### Get website details [GET]

+ Response 200 (application/json)

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

### Update website details [PUT]

+ Request (application/json)

  + Body

      ```
      <!-- include(examples/site-with-config.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

+ Response 200 (application/json)

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

### Delete website [DELETE]

+ Response 200

## Site DNS status [/site/{id}/dns]

+ Parameters
  + id (required, string) - Site UUID

### Check website DNS status [POST]

+ Response 200 (application/json)

  + Body 

       { "valid": true }

## Website discovery [/site/discover{?url}]

### Match URL to a website [GET]

+ Parameters
  + url (required, string) - URL of the website

+ Response 302

  + Headers

            Location: /site/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

+ Response 409

  Grid site belonging to another user was found at the URL

+ Response 404

  No Grid site was found for the URL

  + Body

# Group Content Management

## Share [/share]

### Sharing content [POST]

Users can share content to The Grid. The shared items will be normalized, analyzed and made available via the item API.
Sharing creates a Job, whos progress can be monitored using the /job API.

There are typically three different things you can be sharing:

* Full article pages: share with URL
* HTML fragments: selection or img tag. Share with content, type text/html and with the URL of the originating page

Note that publishing an item to a website is a separate step. See /publish

+ Request with JSON payload (application/json)

  + Body

      ```
      <!-- include(examples/share-url-only.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/share.json) -->
      ```

+ Response 202

  Sharing was successful and will be processed.

  + Headers

            Location: /job/b8838e11-1d97-4799-85d8-1aafec52e927

  + Body

+ Response 422

  Missing required parameters

  + Body

+ Response 403

  Not allowed to share to the specified website

  + Body

## Random content [/share/random{?category,number}]
{'fraction_non_alphanumeric': 0.1250415696707682, 'fraction_numerical': 0.024165835273251304, 'mean_word_length': 2.6482005661140318, 'pattern_counts': {'":': 2, '<': 27, '<?xml version=': 0, '>': 27, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6093596', 'n_tokens_mistral': 2946, 'n_tokens_neox': 2650, 'n_words': 883}