• Endpoint
• Authentication
• User Details
• Entries
  • List Entries
  • List Team Entries
  • Add Entry
  • Add Team Entry
• Switching Current Team
• Client Versions
• People
• Session addresses (no token)

API

The ClipLine restful API allows users to list and add clipboard entries.

Endpoint

Authentication

Requests to the API need to be authenticated using Bearer Tokens. Appropriate tokens can be created here.

Tokens work the same with two-factor authentication on: the code is only asked for when logging in in the browser.

Each request to the API needs to contain the following header fields:

Authorization: Bearer [your_token]
Accept: application/json

User Details

This request lists the current user information.

Required Parameters

None

Example Response

{
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "current_team_id": 1,
    "teams": [
        {
            "id": 1,
            "name": "Team 1"
        },
        {
            "id": 2,
            "name": "Team 2"
        }
    ],
    "features": ["burn", "updates", "direct"]
}

features lists what this server supports beyond the basics. A client checks for burn before it sends an entry with burn, because an older server would ignore the flag and store the text as a normal entry. updates means the server answers Client Versions. direct means it takes to (Add Entry) and answers People.

List Entries

This request lists all entries the authenticated user can access.

Required Parameters

None

Example Response

Code: 200

Content:

[
    {
        "key": "clipline_entries:2_66953114b4e918.01545756",
        "value": "Clipboard Text Data",
        "displayValue": "Clipboard Text Data",
        "created_at": "2024-07-15T14:29:22.435315Z"
    },
    {
        "key": "clipline_entries:2_66953136111d76.92600808",
        "value": "http://clipline.test/download/files/N4wqPiFqx2U40AEKksNS0o17t5m1CPTBSfZNxzxr.txt",
        "displayValue": "Clipboard File.txt",
        "created_at": "2024-07-15T14:27:09.536224Z"
    }
]

List Team Entries

This request lists all entries the authenticated user can access.

Required Parameters

None

Example Responses

Code: 200

Content:

[
    {
        "key": "clipline_entries:2_66953114b4e918.01545756",
        "value": "Clipboard Text Data",
        "displayValue": "Clipboard Text Data",
        "created_at": "2024-07-15T14:29:22.435315Z"
    },
    {
        "key": "clipline_entries:2_66953136111d76.92600808",
        "value": "http://clipline.test/download/files/N4wqPiFqx2U40AEKksNS0o17t5m1CPTBSfZNxzxr.txt",
        "displayValue": "Clipboard File.txt",
        "created_at": "2024-07-15T14:27:09.536224Z"
    }
]

Code 404

Content:

{
    "message": "No query results for model ..."
}

Code: 403

Content:

{
    "message": "This action is unauthorized."
}

Add Entry

Users can add entries using the following request:

Required Parameters

Optional Parameters

Listings mark direct entries with "direct": "in" (sent to you) or "out" (sent by you) and recipient_name; other entries have "direct": null.

Example Responses

Code: 200

Content:

{
    "message": "{Entry|File} added"
}

Code 422

Content:

{
    "message": "The entry field is required when file is not present. (and 1 more error)",
    "errors": {
        "entry": [
            "The entry field is required when file is not present."
        ],
        "file": [
            "The file field is required when entry is not present."
        ]
    }
}

Add Team Entry

Users can add team entries using the following request:

Required Parameters

Optional Parameters

Example Responses

Code: 200

Content:

{
    "message": "{Entry|File} added"
}

Code 422

Content:

{
    "message": "The entry field is required when file is not present. (and 1 more error)",
    "errors": {
        "entry": [
            "The entry field is required when file is not present."
        ],
        "file": [
            "The file field is required when entry is not present."
        ]
    }
}

Code 404

Content:

{
    "message": "No query results for model ..."
}

Code: 403

Content:

{
    "message": "This action is unauthorized."
}

Take a Burn-After-Reading Entry

Entries with "burn": true come without their text in every listing: value and displayValue hold 🔥 Burn after reading – update Clipline to copy it. This request returns the text once and deletes the entry for everyone, also when the author takes it.

Required Parameters

Example Responses

Code: 200

{
    "key": "clipline_entries:1_6aeca25d0bbc60.24501880",
    "type": "string",
    "value": "s3cret",
    "displayValue": "s3cret",
    "burn": true,
    "created_at": "2026-11-05T15:35:57.049705Z"
}

Code: 410

{
    "message": "Already taken by someone else."
}

404 means the key exists but isn't yours to take, or the entry isn't a burn-after-reading entry.

People

The people you can send a direct entry to (to in Add Entry): the members of all your teams, once each, without you, sorted by name. The feed lists them too, as people.

Example Response

[
    {"id": 7, "name": "Anna Berger", "email": "[email protected]"},
    {"id": 9, "name": "Ben Köhler", "email": "[email protected]"}
]

Client Versions

The version of each desktop client this server offers, for update checks. Clients that haven't been built on the server are left out. The url is a public download (no token needed); check the file against sha256 before you run it. size is in bytes.

Required Parameters

None

Example Response

{
    "clients": {
        "windows": {
            "version": "1.3.0",
            "url": "https://clipline.example.com/download/windows/clipline-setup",
            "sha256": "5c091ff6108dcfd03747adf1739edda90bb9e1a4fd199ae38fcf261c6e676f10",
            "size": 56412019
        },
        "linux-tray": {"version": "2.2.0", "url": "https://clipline.example.com/download/linux/clipline-tray", "sha256": "…", "size": 22480},
        "linux-cli": {"version": "2.2.0", "url": "https://clipline.example.com/download/linux/clipline", "sha256": "…", "size": 14110},
        "macos": {"version": "1.2.0", "url": "https://clipline.example.com/download/macos/clipline", "sha256": "…", "size": 2310144}
    }
}

Switching Current Team

Users can switch the current team:

Required Parameters

None

Optional Parameters

None

Example Responses

Code: 200

Content:

{
    "message": "Switched Team"
}

Code 404

Content:

{
    "message": "No query results for model ..."
}

Code: 403

Content:

{
    "message": "This action is unauthorized."
}

Session addresses (no token)

Sessions have their own plain-text addresses outside /api, which need no token – the session code is the credential. They answer text/plain (files as downloads with their name) and 404 Session code is invalid or expired. for an unknown code.

Adding answers 201 with Saved as entry {n} of session {code}. and the command to fetch it; an empty body answers 422. /session/{code}/list, /session/{code}/latest and /session/{code}/entry/{n} are the older, longer form of the same. Examples are on Command line (curl).