---
title: "The journal and ref"
description: "What the decision journal keeps, how long, and how your own id (ref) lets you find a decision."
canonical_url: "https://openshield.dev/docs/journal-and-ref"
---
# The journal and ref

> What the decision journal keeps, how long, and how your own id (ref) lets you find a decision.

The journal is the record of the decisions the API made for your organization. You read it in the [dashboard](https://openshield.dev/dashboard/journal), filter it, and export it.

## What a row holds

One row per check:

- the time and the `request_id`;
- the key, by id and name;
- the kind (image or text), the workflow and its version;
- the decision, and the reasons with their scores and thresholds;
- the categories the workflow could not check (`unchecked`);
- how long the check took, and the size of the content in bytes;
- your `ref`, if you sent one.

**Never stored**: the content itself, whatever it is, the IP address of your users, and their browser. The journal keeps what the API decided, never what it was asked about.

## How long it is kept

<table>
<thead>
  <tr>
    <th>
      Plan
    </th>
    
    <th>
      Days kept
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Free
    </td>
    
    <td>
      7
    </td>
  </tr>
  
  <tr>
    <td>
      Starter, Growth, Scale
    </td>
    
    <td>
      30
    </td>
  </tr>
</tbody>
</table>

Older rows are deleted every day. Export what you need to keep for longer.

## ref: your own id for the content

`ref` is the id your system gives the image or the text: a post id, a message id, a user id. It is 1 to 128 characters with no control character.

```bash
curl -X POST "https://api.openshield.dev/v1/image?ref=post_8812" \
  -H "Authorization: Bearer $OPENMOD_API_KEY" \
  --data-binary @photo.jpg
```

The API echoes it in the answer and keeps it in the journal. When a user asks why their upload was refused, you search the journal for the `ref` and see the decision, the reasons and the workflow version, and openshield never had to keep the upload to answer.

<warning>

Do not put personal data in a `ref`. Use an opaque id from your own database.

</warning>

## Filtering and exporting

The journal screen filters by:

- the decision (accepted, to review, rejected);
- the kind, the key and the workflow;
- a range of time;
- the start of a `ref`.

A row opens a detail panel with every reason. **Export** writes the rows of the filter, for any range inside the retention window, as JSONL or CSV.

## From a refusal to the row

Every answer carries a `request_id`, in the body and in the `X-Request-Id` header. Log it next to your own records: it is the id of the journal row, and the first thing to quote if you write to support.


## Sitemap

See the full [sitemap](https://openshield.dev/sitemap.md) for all pages.