<!--
  immut documentation, machine-readable.

  Everything in one file:  https://www.immut.io/llms-full.txt
    What immut is, which integration path to choose, authentication and scopes, and the COMPLETE
    API reference: every endpoint with parameters, responses and a runnable curl. Fetch this first
    if you intend to call the API.

  Index of all pages:      https://www.immut.io/llms.txt
  OpenAPI contract:        https://www.immut.io/docs/openapi.json
  This page as HTML:       https://www.immut.io/docs/api/other/get-share-links

  Any page on this site is available as raw markdown by appending .md to its URL.
-->


# What this organisation has shared, and whether each link is still live

`GET /share-links`

**Required scope:** `documents:read`

Revoked and expired links are included by default, because "who had access last month" is a real question.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `resourceType` | query | no | document \| folder \| workspace |
| `resourceId` | query | no | only links for this resource |
| `activeOnly` | query | no | true hides revoked and expired links |
| `page` | query | no | default 1 |
| `limit` | query | no | default 20, max 100 |

## Responses

| Status | Meaning |
|---|---|
| `200` | Success Returns: per row: id, resourceType, resourceId, accessLevel, expiresAt, isActive, expired, accessCount (every open), openEventsRecorded and accessLogTruncated (the access log keeps only the newest 200), createdAt. For links you created you also get recipientEmails and openedBy (the emails that actually opened it); for links someone else in the organisation created you get recipientCount and openedByCount instead, because a read key must not enumerate every outside party the organisation has ever dealt with. |
| `400` | BadRequest |
| `401` | Unauthorized |
| `403` | Forbidden |
| `429` | RateLimited |

## Example

```bash
curl -X GET "https://backend.immut.io/api/v1/share-links" \
  -H "Authorization: Bearer $IMMUT_API_KEY"
```

## OpenAPI fragment

```json
{
  "/share-links": {
    "get": {
      "operationId": "getsharelinks",
      "summary": "What this organisation has shared, and whether each link is still live. Revoked and expired links are included by default, because \"who had access last month\" is a real question.",
      "description": "What this organisation has shared, and whether each link is still live. Revoked and expired links are included by default, because \"who had access last month\" is a real question.",
      "parameters": [
        {
          "name": "resourceType",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "document | folder | workspace"
        },
        {
          "name": "resourceId",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "only links for this resource"
        },
        {
          "name": "activeOnly",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "true hides revoked and expired links"
        },
        {
          "name": "page",
          "in": "query",
          "required": false,
          "schema": {
            "type": "integer"
          },
          "description": "default 1"
        },
        {
          "name": "limit",
          "in": "query",
          "required": false,
          "schema": {
            "type": "integer"
          },
          "description": "default 20, max 100"
        }
      ],
      "responses": {
        "200": {
          "description": "Success Returns: per row: id, resourceType, resourceId, accessLevel, expiresAt, isActive, expired, accessCount (every open), openEventsRecorded and accessLogTruncated (the access log keeps only the newest 200), createdAt. For links you created you also get recipientEmails and openedBy (the emails that actually opened it); for links someone else in the organisation created you get recipientCount and openedByCount instead, because a read key must not enumerate every outside party the organisation has ever dealt with."
        },
        "400": {
          "$ref": "#/components/responses/BadRequest"
        },
        "401": {
          "$ref": "#/components/responses/Unauthorized"
        },
        "403": {
          "$ref": "#/components/responses/Forbidden"
        },
        "429": {
          "$ref": "#/components/responses/RateLimited"
        }
      },
      "x-required-scope": "documents:read"
    }
  }
}
```