Add a favorite

PUT/api/user/favorites

putUserFavorite

Adds a repository, team, or issue/ticket to the authenticated user's favorites and returns it. Idempotent: favoriting a target twice returns the existing favorite. The caller must be able to read the target; a target that does not exist and one the caller cannot read are the same 404.

Requires authentication using a bearer token or a session cookie — see tokens and scopes.

curl

curl -X PUT 'https://neosource.dev/api/user/favorites' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"target":"string"}'

fetch

fetch("https://neosource.dev/api/user/favorites", {
  method: "PUT",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"target":"string"}),
});

Request bodyrequired

application/json

PutFavoriteRequest

object

`PUT /api/user/favorites`.

targetrequired

FavoriteTargetRef

object

What a favorite points at, on the wire: `{kind, id}`. `id` is the target's typed id (a repo, team or issue id).

idrequired: string
kindrequired: FavoriteKind

Responses

200The favorite

application/json

FavoriteResponse

object

One favorite the caller can currently read.

created_atrequired

integerint64

Unix milliseconds.

favorite_idrequired

string

issue

one of

FavoriteIssueParts
object
A favorited issue or ticket. The flat ref fields are the `IssueLinkTargetLike` shape (`lib/issues/kind.ts`), so the SPA's `issueLinkTargetHref` / `issueLinkTargetRef` accept it unchanged: a ticket sets `team_key` + `team_owner`, a repo issue `primary_repo_id` + `repo_owner` + `repo_name`.
numberrequired
integerint32
primary_repo_id
string | null
`None` for a ticket.
repo_name
string | null
repo_owner
string | null
Repo issues only: the repo route for `owner/repo#N`.
statusrequired
IssueStatus
team_key
string | null
Tickets only: `KEY` in `KEY-N`.
team_owner
string | null
Tickets only: the team's workspace slug.
titlerequired
string
null

labelrequired

string

What the rail paints: the repo slug, the team name, or the issue title.

repo

one of

FavoriteRepoParts
object
A favorited repo's route: `/{owner}/{slug}`.
ownerrequired
string
slugrequired
string
null

targetrequired

FavoriteTargetRef

object

What a favorite points at, on the wire: `{kind, id}`. `id` is the target's typed id (a repo, team or issue id).

idrequired: string
kindrequired: FavoriteKind

team

one of

FavoriteTeamParts
object
A favorited team's route: `/{owner}/teams/{key}`.
keyrequired
string
namerequired
string
ownerrequired
string
The team's workspace slug.
null

403Forbidden — one of: forbidden, needs_scope

application/json

one of

ErrorForbidden
NeedsScopeError
object
`403` body returned when a classic OAuth token is asked for something its granted scopes do not cover — an explicit private listing without `repo`, or the one-click GitHub mirror without `admin:public_key`. `scope` names the missing grant so the client can say exactly what the token lacks. There is no elevation route to widen it any more (a re-link goes through the GitHub App, whose tokens carry no scopes), so the client's answer is to say so, never to start a handshake.
errorrequired
string
Always `needs_scope` — this body exists to carry the extra fields that kind needs.
"needs_scope"
scoperequired
string
The provider scope to request via elevation (e.g. `"repo"`).

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bad Request — one of: invalid_input
401Authentication required
404Not Found — one of: not_found
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget

Schemas

Referenced above. Listed here rather than expanded inline, so the same definition is not repeated at every level.

`FavoriteKind`

string

The closed set of things a favorite can point at. The wire form of a favorite's target kind; [`FavoriteTarget`] carries the typed id.

"repo""team""issue"

`IssueStatus`

string

"backlog""todo""in_progress""in_review""done""cancelled""duplicate"