Submit a highlight to the moderation queue

curl --request POST \
  --url https://www.immersivecommons.com/api/ingest/highlights/pending \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "<string>",
  "story": {}
}
'

import requests

url = "https://www.immersivecommons.com/api/ingest/highlights/pending"

payload = {
    "id": "<string>",
    "story": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({id: '<string>', story: {}})
};

fetch('https://www.immersivecommons.com/api/ingest/highlights/pending', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.immersivecommons.com/api/ingest/highlights/pending",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => '<string>',
    'story' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.immersivecommons.com/api/ingest/highlights/pending"

	payload := strings.NewReader("{\n  \"id\": \"<string>\",\n  \"story\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.immersivecommons.com/api/ingest/highlights/pending")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"<string>\",\n  \"story\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.immersivecommons.com/api/ingest/highlights/pending")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"<string>\",\n  \"story\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "id": "<string>",
  "status": "pending",
  "job_id": "<string>",
  "poll_url": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

highlights

Submit a highlight to the moderation queue

agt_ token required (scope events:submit_recap). Adds a HighlightStory to the pending moderation queue; an operator approves it. ASYNC-JOB: returns 202 Accepted with status: pending, a job_id (= the story id), a poll_url, and a Location response header — all pointing at GET /api/ingest/highlights/pending?id=<job_id>, which returns status: pending while queued or status: gone once it leaves the queue (approved → active, rejected, or expired). IDEMPOTENT: re-submitting the same story id refreshes the pending record without bumping the rate counter; an Idempotency-Key additionally replays the 202 (with the same Location). Rate: 3/token/UTC day.

POST

api

ingest

highlights

pending

Submit a highlight to the moderation queue

curl --request POST \
  --url https://www.immersivecommons.com/api/ingest/highlights/pending \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "<string>",
  "story": {}
}
'

import requests

url = "https://www.immersivecommons.com/api/ingest/highlights/pending"

payload = {
    "id": "<string>",
    "story": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({id: '<string>', story: {}})
};

fetch('https://www.immersivecommons.com/api/ingest/highlights/pending', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.immersivecommons.com/api/ingest/highlights/pending",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => '<string>',
    'story' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.immersivecommons.com/api/ingest/highlights/pending"

	payload := strings.NewReader("{\n  \"id\": \"<string>\",\n  \"story\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.immersivecommons.com/api/ingest/highlights/pending")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"<string>\",\n  \"story\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.immersivecommons.com/api/ingest/highlights/pending")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"<string>\",\n  \"story\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "id": "<string>",
  "status": "pending",
  "job_id": "<string>",
  "poll_url": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "ok": false,
  "error_kind": "<string>",
  "message": "<string>",
  "rate": {
    "current": 123,
    "remaining": 123,
    "limit": 123
  },
  "retry_after_seconds": 123,
  "tier": "<string>",
  "current_tier": "<string>",
  "detail": "<string>"
}

Authorizations

Authorization

string

header

required

Per-member, individually-revocable agent token minted via the device-code flow. Send as Authorization: Bearer agt_.... The scope array in each operation's security requirement names the IC scope the handler enforces.

Scopes

events:submit_recap

Headers

Idempotency-Key

string

Optional. A retry carrying the same key replays the first successful result verbatim instead of creating a second side effect (honored by lib/idempotency.ts, 24h window). Complementary to each endpoint's own semantic dedupe. Absent = no replay.

Maximum string length: 255

Body

application/json

A HighlightStory, or an object wrapping one under story. Validated by lib/highlights-pending.ts.

string

Stable id — re-submitting the same id refreshes the pending record (dedupe).

story

object

Optional wrapper; the story fields may also be sent at the top level.

Response

Accepted into the pending queue. Poll the Location header (or poll_url) for the job's status.

boolean

required

string

required

status

enum<string>

required

Available options:

pending

job_id

string

Async-job handle (= id) to poll this submission with. Mirrors the Location header + poll_url.

poll_url

string

Status-poll URL: GET /api/ingest/highlights/pending?id=<job_id> → { status: pending | gone }. Same URL as the Location response header.

rate

object

Per-token rate-limit snapshot returned by write endpoints.

Show child attributes

expires_at

string<date-time>

events

batch

directory

resources

account

leaderboard

research

highlights

feedback

auth

payments

membership

Submit a highlight to the moderation queue

Authorizations

Scopes

Headers

Body

Response