flags

8 endpoints at a glance

Method	Path	Summary
GET	/flags/	List Flags
POST	/flags/	Create Flag
DELETE	/flags/{flag_id}/	Delete Flag
GET	/flags/{flag_id}/	Get Flag
PATCH	/flags/{flag_id}/	Update Flag
POST	/flags/{flag_id}/done	Set Done
POST	/flags/counts/	Counts For Targets
GET	/flags/for-target/	List For Target

flags

---

List Flags

GET

/flags/

Management-view list. All filters optional; privacy filter
always applied (admins see everything else; non-admins see public

• their own private).

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

collection

doc_id

author

type

priority

done

since_ts

until_ts

q

limit

Type

integer

Default

200

Responses

Successful Response

Content-Type

application/json

[

  

{

  

  

"additionalProperties": "string"

  

}

]

GET

/flags/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

collection

doc_id

author

type

priority

done

since_ts

until_ts

q

limit

Samples

---

Create Flag

POST

/flags/

Authenticated. Validates the target row exists in its collection
so a typo can't create an orphan flag.

Parameters

Header Parameters

authorization

x-api-key

Request Body

application/json

{

  

"target": {

  

  

"collection": "string",

  

  

"doc_id": 0

  

},

  

"type": "issue",

  

"priority": "medium",

  

"notes": "string",

  

"due_date": "string",

  

"url": "string",

  

"private": false

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/flags/

Playground

Headers

authorization

x-api-key

Body

Samples

---

List For Target

GET

/flags/for-target/

Per-target list, newest-first. Same privacy filter as the
management view; convenience route so embedded <FlagList>
components don't need to repeat the management endpoint's full
parameter set.

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

collection*

Type

string

Required

doc_id*

Required

Responses

Successful Response

Content-Type

application/json

[

  

{

  

  

"additionalProperties": "string"

  

}

]

GET

/flags/for-target/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

collection*

doc_id*

Samples

---

Counts For Targets

POST

/flags/counts/

Batched {<collection>:<doc_id>: {open, done}} counter map
for the per-target badge component. Privacy-filtered.

Parameters

Header Parameters

authorization

x-api-key

Request Body

application/json

{

  

"targets": [

  

  

{

  

  

  

"collection": "string",

  

  

  

"doc_id": 0

  

  

}

  

]

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": {

  

  

"additionalProperties": 0

  

}

}

POST

/flags/counts/

Playground

Headers

authorization

x-api-key

Body

Samples

---

Get Flag

GET

/flags/{flag_id}/

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

flag_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/flags/{flag_id}/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

flag_id*

Samples

---

Delete Flag

DELETE

/flags/{flag_id}/

Author OR admin. Hard-delete; no tombstone.

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

flag_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

DELETE

/flags/{flag_id}/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

flag_id*

Samples

---

Update Flag

PATCH

/flags/{flag_id}/

Author OR admin. Patches any subset of type / priority /
notes / due_date / private. Pass due_date: null
explicitly to clear it; omit the key to leave it unchanged.

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

flag_id*

Type

string

Required

Request Body

application/json

{

  

"type": "string",

  

"priority": "string",

  

"notes": "string",

  

"due_date": "string",

  

"url": "string",

  

"private": true

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

PATCH

/flags/{flag_id}/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

flag_id*

Body

Samples

---

Set Done

POST

/flags/{flag_id}/done

Mark done / undone. Author OR admin. Body: {done: true|false}.

Records done_at / done_at_ts / done_by (the username
that flipped the toggle, distinct from the original author) when
going to done; nulls them on the way back.

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

flag_id*

Type

string

Required

Request Body

application/json

{

  

"done": true

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/flags/{flag_id}/done

Playground

Headers

authorization

x-api-key

Variables

Key

Value

flag_id*

Body

Samples

---