# OrgOrg API v1 — Go Links — instructions for AI agents

This document describes the Go Links endpoints of the OrgOrg v1 REST API. Fetch it from https://orgorg.com/docs/api/v1/go-links/agents.md. The full API is documented at https://orgorg.com/docs/api/v1/agents.md.

## Basics

- Base URL: `https://orgorg.com`. All endpoint paths below are relative to it.
- Every request requires an `Authorization: Bearer <token>` header.
- `GET` endpoints take parameters in the URL query string. `POST` endpoints take a JSON body with a `Content-Type: application/json` header.
- All responses are JSON. A non-2xx status means the request failed; the body describes the problem.
- Endpoints are stable, but new response fields may be added without notice — ignore fields you do not recognize.

## Getting a token

Tokens are created by a signed-in user at https://orgorg.com/docs/credentials and inherit that user's permissions in their organization. If you do not have a token, ask your user to create one there. Verify a token works with:

```sh
curl "https://orgorg.com/api/v1/auth/test" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

A valid token returns `{ "ok": true, ... }`.

## Go Links

List, search, and save go links. Human-readable docs: https://orgorg.com/docs/api/v1/go-links

### List Go Links

`GET /api/v1/go/find`

List all go links or search for go links by query

Parameters:

- `q` (string, optional) — Search query

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/go/find?q=duck" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  links: {
    name: string;
    description: string;
    url: string;
  }[]
}
```

### Save Go Link

`POST /api/v1/go/save`

Update existing or create a new Go Link.

Parameters:

- `name` (string, required) — Name of the go link to update
- `url` (string, optional) — URL of the go link
- `description` (string, optional) — Description of the go link

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/go/save" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lunch",
    "description": "saved lunch description via api"
  }'
```

Response shape:

```ts
{
  id: number;
  name: string;
  url: string;
  description: string;
}
```