# health.hats.listGrants

> Grants the caller gave, as a patient, and grants the caller holds, as a grantee: one entry per request, newest first. Authenticated by service auth, so each caller sees only their own.

- Kind: query
- Authority: hats.health
- Lexicon: 1
- Published by [hats.health](https://lexicon.garden/identity/did:plc:uvvhtareovj2oaregs7vsibv), the NSID's authority

## Links

- [Documentation](https://lexicon.garden/lexicon/did:plc:uvvhtareovj2oaregs7vsibv/health.hats.listGrants)
- [Schema JSON](https://lexicon.garden/lexicon/did:plc:uvvhtareovj2oaregs7vsibv/health.hats.listGrants/schema.json)
- [Analytics](https://lexicon.garden/lexicon/did:plc:uvvhtareovj2oaregs7vsibv/health.hats.listGrants/analytics)

## Query (`health.hats.listGrants`)

Type: query · GET

### Output (application/json)

- `grants` (array, required)
  - `items` (ref)
    - Reference: `#grant`

## #grant (`health.hats.listGrants#grant`)

Type: object

One request's grants and where they stand. The caller is the patient or the grantee.

### Properties

- `answeredAt` (string · datetime): When the patient approved or declined the request.
- `createdAt` (string · datetime, required)
- `expiresAt` (string · datetime)
- `grant` (string · at-uri): The grant record in the patient's audit space that backs an approval.
- `grantee` (string · did, required)
- `id` (string, required): The request's identifier, as listRequests and answerRequest use it.
- `institution` (string): The institution the grantee acts for, as the registry names it.
- `patient` (string · did, required)
- `reason` (string, required): HL7 PurposeOfUse code the request was made under.
- `reasonText` (string): What the requester said beside the code: for break-glass, why the patient couldn't be asked.
- `revokedAt` (string · datetime): When the patient revoked the approval.
- `role` (string): The grantee's NUCC Health Care Provider Taxonomy code, from the provider registry.
- `spaces` (array, required)
  - `items` (ref)
    - Reference: `#space`
- `status` (string, required)
  - Constraints: knownValues: pending | granted | declined | revoked | expired

## #space (`health.hats.listGrants#space`)

Type: object

### Properties

- `access` (string, required)
  - Constraints: knownValues: read | write
- `skey` (string, required)
- `spaceType` (string · nsid, required)

## Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "grant": {
      "description": "One request's grants and where they stand. The caller is the patient or the grantee.",
      "properties": {
        "answeredAt": {
          "description": "When the patient approved or declined the request.",
          "format": "datetime",
          "type": "string"
        },
        "createdAt": {
          "format": "datetime",
          "type": "string"
        },
        "expiresAt": {
          "format": "datetime",
          "type": "string"
        },
        "grant": {
          "description": "The grant record in the patient's audit space that backs an approval.",
          "format": "at-uri",
          "type": "string"
        },
        "grantee": {
          "format": "did",
          "type": "string"
        },
        "id": {
          "description": "The request's identifier, as listRequests and answerRequest use it.",
          "type": "string"
        },
        "institution": {
          "description": "The institution the grantee acts for, as the registry names it.",
          "type": "string"
        },
        "patient": {
          "format": "did",
          "type": "string"
        },
        "reason": {
          "description": "HL7 PurposeOfUse code the request was made under.",
          "type": "string"
        },
        "reasonText": {
          "description": "What the requester said beside the code: for break-glass, why the patient couldn't be asked.",
          "type": "string"
        },
        "revokedAt": {
          "description": "When the patient revoked the approval.",
          "format": "datetime",
          "type": "string"
        },
        "role": {
          "description": "The grantee's NUCC Health Care Provider Taxonomy code, from the provider registry.",
          "type": "string"
        },
        "spaces": {
          "items": {
            "ref": "#space",
            "type": "ref"
          },
          "type": "array"
        },
        "status": {
          "knownValues": [
            "pending",
            "granted",
            "declined",
            "revoked",
            "expired"
          ],
          "type": "string"
        }
      },
      "required": [
        "id",
        "patient",
        "grantee",
        "reason",
        "status",
        "spaces",
        "createdAt"
      ],
      "type": "object"
    },
    "main": {
      "description": "Grants the caller gave, as a patient, and grants the caller holds, as a grantee: one entry per request, newest first. Authenticated by service auth, so each caller sees only their own.",
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "grants": {
              "items": {
                "ref": "#grant",
                "type": "ref"
              },
              "type": "array"
            }
          },
          "required": [
            "grants"
          ],
          "type": "object"
        }
      },
      "type": "query"
    },
    "space": {
      "properties": {
        "access": {
          "knownValues": [
            "read",
            "write"
          ],
          "type": "string"
        },
        "skey": {
          "type": "string"
        },
        "spaceType": {
          "format": "nsid",
          "type": "string"
        }
      },
      "required": [
        "spaceType",
        "skey",
        "access"
      ],
      "type": "object"
    }
  },
  "id": "health.hats.listGrants",
  "lexicon": 1
}
```