Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Attachments

Images and documents on a record: list them, open a document, and attach a file.

Images and documents on a record

GET https://api.tiny.plus/v2/attachments?related_id={{id}}

Lists what the record's Images & Docs panel lists in tiny+, in the same order.

curl "https://api.tiny.plus/v2/attachments?related_id=66" \
  -H "Authorization: Bearer {{user_access_token}}"
{
    "related_id": "66",
    "flavour": "projects",
    "allow_images": true,
    "allow_documents": true,
    "perm_edit": true,
    "images": [
        {
            "id": "2352",
            "name": "Ashgrove-Golf-Club-retirement-village-render.jpg",
            "description": null,
            "credit": null,
            "thumb_url": "https://….blob.core.windows.net/account-3/thumbs/e8ef5be8fa2ef4444656c0259276d179.jpg",
            "full_url": "https://….blob.core.windows.net/account-3/images/e8ef5be8fa2ef4444656c0259276d179.jpg",
            "width": 2048,
            "height": 1318,
            "is_default": true,
            "created_date": "2020-01-06T02:27:37Z"
        }
    ],
    "documents": [
        {
            "id": "1292",
            "name": "a primer on tiny 20170314.pdf",
            "description": null,
            "doctype": "pdf",
            "created_date": "2019-11-29T03:34:58Z"
        }
    ]
}

  • allow_images and allow_documents say which the record type keeps. Companies and contacts keep documents only, so their images is always empty.

  • Images are in order of name, then id, and documents in order of name.

  • thumb_url is a 200×200 crop and full_url the whole image. Both are lasting URLs.

  • is_default marks the record's main picture.

  • A document carries no URL. Ask for one when it's opened: see below.

  • perm_edit says whether the token's user may attach files to the record.

  • On an account with user docs switched on, user_docs lists the record's user docs, each with id, name and record_url.

  • Dates are in UTC. use_cache=0 reads past the cache.

Case
Response

related_id missing or not a number

400 {"error": "Must specify a valid record id."}

No such record, or a type the API doesn't serve

404 {"error": "Record not found"}

A deleted record

410 {"error": "This record has been deleted."}

A confidential record the token's user can't see

403 {"error": "This record is confidential."}

Open a document

GET https://api.tiny.plus/v2/attachments/{{id}}

Gives a link that opens a document, or an image, for the next ten minutes.

  • The link needs no token, so a browser can open it. It opens the file under its own name and type: a PDF opens as a PDF.

  • It stops working at expires_at, in UTC. Ask again rather than keeping it.

  • Only a file on at least one record the token's user can see has a link. Anything else, including a file whose stored copy is missing, answers 404 {"error": "File not found."}.

Attach a file

POST https://api.tiny.plus/v2/attachments

Attaches a file — an image or a document — to a record.

The request

Field
Description

related_id

Required. The record to attach the file to. It must be a record the token's user can see and edit.

attachments

Required. One file as an object, or several as an array of objects.

Each file object has:

Field
Description

data

The file's bytes, base64-encoded. Send the base64 on its own, not a data:… URL.

mime_type

The file's type, such as image/png or application/pdf. It decides whether the file is stored as an image or a document — see below.

name

The file name. Its extension is used in the stored file's path.

Images and documents

The mime_type decides how the file is kept:

  • image/png, image/jpeg and image/gif are stored as images: re-encoded, rotated upright, and given a thumbnail. An animated GIF keeps its animation. An image attached to a record becomes that record's main picture.

  • image/webp, image/avif, image/bmp, image/heic, image/heif, image/tiff and image/svg+xml are stored as images too, converted: to a PNG if any of the picture is transparent, and to a JPEG if not. The file keeps the name it was sent with. A HEIC or TIFF larger than 4096 pixels on its longest side is scaled down to that, and only the first page of a TIFF is kept. An SVG is drawn 2048 pixels on its longest side. A file that can't be read, such as an animated WebP or an SVG that refers to other files, is skipped.

  • Everything else is stored as a document, unchanged.

The response

200 with an array of the new file ids, one per file that was stored, as strings. Attaching the same image bytes twice returns the existing image's id and links it to the record again.

Where the file goes in tiny+:

  • An image appears in the record's Images panel and becomes its main picture. On a project or event, it's also posted to the News Feed, unless that record is confidential.

  • A document appears in the record's Documents panel.

Nobody is notified. The new file is in the record's images and documents straight away.

Errors

Case
Response

A read-only token

403 {"error": "This token is read-only."}

related_id missing, not a number, deleted, in another account, or a confidential record the token's user can't see

400 {"error": "Must specify a valid record id."}

A record the token's user can't edit

403 {"error": "You may not edit this record: it is not one you own or administer."}

A post that isn't the token's user's own, unless they're a News Feed admin

403 {"error": "You may not change this post: it is not yours."}

attachments missing, or not an object or array

400 {"error": "Attachments data not valid."}

Nothing is stored when the request is refused.

A file object that's missing data, mime_type or name, or whose bytes aren't the image its mime_type names, is skipped rather than reported. Check the returned array has an id for each file you sent.

PreviousAsk filters
NextWebhooks

Last updated

Was this helpful?