Perkeep

https://perkeep.org/doc
Admin
Perkeep is a personal storage system that lets you store all your content forever with powerful...
Tokens:22,166
Snippets:308
Trust Score:8.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### GET Request for Blob Enumeration

Source: https://perkeep.org/doc/protocol/blob-enumerate

This is an example of an HTTP GET request to the /camli/enumerate-blobs endpoint. It shows how to request blobs, optionally specifying a starting point with 'after' and a maximum number of results with 'limit'.

```http
GET /camli/enumerate-blobs?after=&limit= HTTP/1.1
Host: example.com


```

--------------------------------

### Server Configuration Example

Source: https://perkeep.org/doc/client-config

Defines multiple server configurations with different authentication and trusted certificate settings.

```json
  "servers": {
    "localhost": {
      "server": "http://localhost:3179",
      "default": true,
      "auth": "userpass:foo:bar"
    },
    "backup": {
      "server": "https://some.remote.com",
      "auth": "userpass:pony:magic",
      "trustedCerts": ["ffc7730f4b"]
    }
  }


```

--------------------------------

### JSON Signing Discovery Response

Source: https://perkeep.org/doc/protocol/jsonsign

This is an example of the response from the discovery handler when a GET request is made with no options. It provides details about the public key and the URLs for signing and verification.

```json
{
    "publicKey": "/sighelper/camli/sha1-f72d9090b61b70ee6501cceacc9d81a0801d32f6",
    "publicKeyBlobRef": "sha1-f72d9090b61b70ee6501cceacc9d81a0801d32f6",
    "publicKeyId": "94DE83C46401800C",
    "signHandler": "/sighelper/camli/sig/sign",
    "verifyHandler": "/sighelper/camli/sig/verify"
}

```

--------------------------------

### Schema Blob Example

Source: https://perkeep.org/doc/terms

A Perkeep-recognized data structure serialized as a JSON object. It must include 'camliVersion' and 'camliType' keys and start with an opening brace. Any valid JSON serialization is acceptable.

```json
{
  "aKey": "itsValue",
  "camliType": "foo",
  "camliVersion": 1,
  "somethingElse": [1, 2, 3]
}
```

--------------------------------

### Configure Perkeep Publishing Gallery

Source: https://perkeep.org/doc/server-config

Example of configuring the image gallery view for publishing. Ensure 'camliRoot' matches the permanode attribute.

```json
{
  "publish": {
    "/pics/": {
      "camliRoot": "mypics",
      "cacheRoot": "/home/joe/var/perkeep/blobs/cache",
      "goTemplate": "gallery.html"
    }
  }
}

```

--------------------------------

### Generate Default Client Configuration

Source: https://perkeep.org/doc/client-config

Run 'pk put init' to generate a default client configuration file. The output shows an example structure.

```bash
cat $CONFIGDIR/client-config.json
```

--------------------------------

### Blobref Examples

Source: https://perkeep.org/doc/terms

Examples of valid blob references, which consist of a cryptographic hash function name and the digest of the blob's bytes in hex. Concatenating these with a hyphen is the common representation.

```plaintext
sha1-f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
```

```plaintext
md5-d3b07384d113edec49eaa6238ad5ff00
```

```plaintext
sha256-b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
```

--------------------------------

### Default client-config.json Structure

Source: https://perkeep.org/doc/client-config

An example of a default Perkeep client configuration file, including identity, ignored files, and server settings.

```json
{
  "identity": "43AD73B1",
  "ignoredFiles": [
    ".DS_Store"
  ],
  "servers": {
    "localhost": {
      "auth": "localhost",
      "default": true,
      "server": "http://localhost:3179"
    }
  }
}

```

--------------------------------

### GET Request Example for Blob Stat

Source: https://perkeep.org/doc/protocol/blob-stat

Demonstrates a GET request to the blob stat endpoint. Use this for a small number of blobs to avoid URL length issues.

```http
GET /some-blob-root/camli/stat?camliversion=1&blob1=sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8 HTTP/1.1
Host: example.com


```

--------------------------------

### Trusted Certificates Example

Source: https://perkeep.org/doc/client-config

Example of specifying trusted TLS server certificate fingerprints for HTTPS connections.

```json
"trustedCerts": ["ffc7730f4bf00ba4bad0"]
```

--------------------------------

### Perkeep Primary Storage Configuration

Source: https://perkeep.org/doc/server-config

Example of a primary storage configuration using 'storage-blobpacked' handler. This defines how blobs are stored and indexed.

```json
/bs/": {
        "handler": "storage-blobpacked",
        "handlerArgs": {
            "largeBlobs": "/bs-packed/",
            "metaIndex": {
                "file": "/home/you/var/perkeep/blobs/packed/packindex.leveldb",
                "type": "leveldb"
            },
            "smallBlobs": "/bs-loose/"
        }
    },

```

--------------------------------

### Configure Perkeep Publishing with Reverse Proxy

Source: https://perkeep.org/doc/server-config

Example for publishing configuration when Perkeep runs behind a reverse proxy. Includes API host, listen address, and backend URL.

```json
{
    "publish": {
        "/pics/": {
            "camliRoot": "mypics",
            "cacheRoot": "/home/joe/var/perkeep/blobs/cache",
            "goTemplate": "gallery.html",
            "apiHost": "http://localhost:3179/",
            "listen": ":44352",
            "backendURL": "http://localhost:44352/"
        }
    }
}

```

--------------------------------

### Blob Stat Response Example

Source: https://perkeep.org/doc/protocol/blob-stat

An example JSON response from the blob stat endpoint, indicating blob availability and size, and whether long-polling is supported.

```json
{
   "stat": [
      {"blobRef": "sha1-abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",
       "size": 12312}
   ],
   "canLongPoll": true
}

```

--------------------------------

### Example Permanode Blob

Source: https://perkeep.org/doc/terms

A sample permanode blob, generated using `pk put --permanode`. This is a signed schema blob with no data intended for mutation, serving as a stable reference to a Perkeep object.

```json
{"camliVersion": 1,
  "camliSigner": "sha1-c4da9d771661563a27704b91b67989e7ea1e50b8",
  "camliType": "permanode",
  "random": "HJ#/s#S+Q$rh:lHJ${)v"
,"camliSig":"iQEcBAABAgAGBQJNQzByAAoJEGjzeDN/6vt85G4IAI9HdygAD8bgz1BnRak6fI+L1dT56MxNsHyAoJaNjYJYKvWR4mrzZonF6l/I7SlvwV4mojofHS21urL8HIGhcMN9dP7Lr9BkCB428kvBtDdazdfN/XVfALVWJOuZEmg165uwTreMOUs377IZom1gjrhnC1bd1VDG7XZ1bP3PPxTxqppM0RuuFWx3/SwixSeWnI+zj9/Qon/wG6M/KDx+cCzuiBwwnpHf8rBmBLNbCs8SVNF3mGwPK0IQq/l4SS6VERVYDPlbBy1hNNdg40MqlJ5jr+Zln3cwF9WzQDznasTs5vK/ylxoXCvVFdOfwBaHkW1NHc3RRpwR0wq2Q8DN3mQ==gR7A"}
```

--------------------------------

### Blob Enumeration Response

Source: https://perkeep.org/doc/protocol/blob-enumerate

This is an example JSON response from the /camli/enumerate-blobs endpoint. It includes a list of blobs with their references and sizes, a 'continueAfter' token for pagination, and a flag indicating if long-polling is supported.

```json
{
  "blobs": [
    {"blobRef": "md5-acbd18db4cc2f85cedef654fccc4a4d8",
     "size": 3},
    {"blobRef": "sha1-0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33",
     "size": 3},
  ],
  "continueAfter": "sha1-0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33",
  "canLongPoll": true,
}

```

--------------------------------

### POST Request Example for Blob Stat

Source: https://perkeep.org/doc/protocol/blob-stat

Demonstrates a POST request to the blob stat endpoint. This method is safer for a larger number of blobs due to URL length limitations.

```http
POST /some-blob-root/camli/stat HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: example.com

camliversion=1&
blob1=sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8&
blob2=sha1-abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd&
blob3=sha1-deadbeefdeadbeefdeadbeefdeadbeefdeadbeef


```

--------------------------------

### Discovery Handler

Source: https://perkeep.org/doc/protocol/jsonsign

The discovery handler provides information about the signing and verification endpoints. It responds to a GET request.

```APIDOC
## GET [jsonSignRoot]/camli/sig/discovery

### Description
Retrieves discovery information for the JSON signing and verification handlers.

### Method
GET

### Endpoint
[jsonSignRoot]/camli/sig/discovery

### Response
#### Success Response (200)
- **publicKey** (string) - The public key path.
- **publicKeyBlobRef** (string) - The public key blob reference.
- **publicKeyId** (string) - The public key ID.
- **signHandler** (string) - The URL path for the signing handler.
- **verifyHandler** (string) - The URL path for the verification handler.

#### Response Example
```json
{
    "publicKey": "/sighelper/camli/sha1-f72d9090b61b70ee6501cceacc9d81a0801d32f6",
    "publicKeyBlobRef": "sha1-f72d9090b61b70ee6501cceacc9d81a0801d32f6",
    "publicKeyId": "94DE83C46401800C",
    "signHandler": "/sighelper/camli/sig/sign",
    "verifyHandler": "/sighelper/camli/sig/verify"
}
```
```

--------------------------------

### Bytes Blob Schema Example

Source: https://perkeep.org/doc/schema/bytes

This JSON object demonstrates the structure of a Bytes Blob, including required and optional fields for defining byte regions, referencing raw bytes, or specifying recursive byte descriptions. It illustrates how to represent contiguous byte regions, sparse file holes, and large files composed of smaller parts.

```json
{
 "camliVersion": 1,
 "camliType": "bytes",

  // Required.  Array of contiguous regions of bytes.  Zero or more elements.
  //
  // Each element must have:
  //    "size": the number of bytes that this element contributes to array of bytes.
  //            Required, and must be greater than zero.
  //
  // At most one of:
  //    "blobRef": where to get the raw bytes from.  if this and "bytesRef"
  //               are missing, the bytes are all zero (e.g. a sparse file hole)
  //    "bytesRef": alternative to blobRef, where to get the range's bytes
  //                from, but pointing recursively at a "bytes" schema blob
  //                describing the range, recursively. large files are made of
  //                these in a hash tree.  it is an error if both "bytesRef"
  //                and "blobRef" are specified.
  //
  //    The absence of "blobRef" or "bytesRef" is used to represent a hole in a
  //    sparse file. Or just zeros.
  //
  // Optional:
  //    "offset": the number of bytes into blobRef or bytesRef to skip to
  //              get the necessary bytes for the range. usually zero (unspecified)
  "parts": [
    {"blobRef": "digalg-blobref", "size": 1024},
    {"bytesRef": "digalg-blobref", "size": 5000000, "offset": 492 },
    {"size": 1000000},
    {"blobRef": "digalg-blobref", "size": 10},
   ]
}

```

--------------------------------

### Blob Not Found

Source: https://perkeep.org/doc/protocol/blob-get

A GET request for a non-existent blob returns a 404 Not Found status.

```http
GET /camli/sha1-126249fd8c18cbb5312a5705746a2af87fba9538 HTTP/1.1
Host: example.com


```

```http
HTTP/1.1 404 Not Found


```

--------------------------------

### Static Set Schema Example

Source: https://perkeep.org/doc/schema/static-set

This JSON structure defines a static set, which can contain individual members or be composed of other static sets (subsets). Use this for presenting a snapshot of members.

```json
{
 "camliVersion": 1,
 "camliType": "static-set",

 // Either one of members or mergeSets is required, and they are mutually exclusive.
 // If a directory has enough children that the resulting static-set blob
 // would be larger than the maximum schema blob size, then the children are
 // actually spread (recursively, if needed) onto several static-sets. When that is
 // the case, these subsets are stored in mergeSets instead of members. Members
 // stores the actual file or directory schemas (the actual members of the top
 // static-set entity).
 //
 // Members can be ordered or unordered, depending on context/needs. If unordered,
 // it's recommended but not required to sort the blobrefs.
 "members": [
    "digalg-blobref-item1",  // maybe a file?
    "digalg-blobref-item2",  // maybe a directory?
    "digalg-blobref-item3",  // maybe a symlink?
    "digalg-blobref-item4",  // maybe a permanode?
    "digalg-blobref-item5",  // ... don't know until you fetch it
    "digalg-blobref-item6",  // ... and what's valid depends on context
    "digalg-blobref-item7",  // ... a permanode in a directory would
    "digalg-blobref-item8"   // ... be invalid, for instance.
 ],
 "mergeSets": [
    "digalg-blobref-subset1",  // another static-set, with either members or subsets
    "digalg-blobref-subset2",  // ''
    "digalg-blobref-subset3",  // ''
    "digalg-blobref-subset4"   // ''
 ]
}

```

--------------------------------

### Negated Predicate with 'or' Grouping

Source: https://perkeep.org/doc/search-ui

Shows how to negate a predicate using a leading minus sign and combine it with other predicates using 'or'. This example filters for images outside a date range or located in Amsterdam.

```text
-(after:"2010-01-01" before:"2010-03-02T12:33:44") or loc:"Amsterdam"
```

--------------------------------

### Raw JSON Constraint Search

Source: https://perkeep.org/doc/search-ui

Provides an example of using the 'raw' operator to match a complex JSON search constraint. This allows for advanced filtering based on nested attributes and value sets.

```json
raw:{"permanode": {"attr": "camliContent", "valueInSet": {"file": {"mediaTag": {"tag": "title", "string": {"hasPrefix": "Bohemian"}}}}}}
```

--------------------------------

### Initialize MySQL Database with pk

Source: https://perkeep.org/doc/server-config

Use the 'pk dbinit' command to initialize your MySQL database for Perkeep. Ensure you provide the correct user, password, host, and dbname.

```bash
pk dbinit --user=foo --password=bar --host=localhost --dbname=camliprod --wipe
```

--------------------------------

### Get Blob Contents

Source: https://perkeep.org/doc/protocol/blob-get

Use a GET request to retrieve the full contents of a blob. The response includes Content-Length and the blob data.

```http
GET /camli/sha1-126249fd8c18cbb5312a5705746a2af87fba9538 HTTP/1.1
Host: example.com


```

```http
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: <the blob length in bytes>

<the blob contents>


```

--------------------------------

### Configure Image Gallery Publishing

Source: https://perkeep.org/doc/publishing/README

Configure the server to publish image galleries under the /pics/ path. Ensure the camliRoot attribute matches the root node's configuration.

```json
{
  "publish": {
    "/pics/": {
      "camliRoot": "mypics",
      "cacheRoot": "/home/joe/var/camlistore/blobs/cache",
      "goTemplate": "gallery.html"
    }
  }

}
```

--------------------------------

### Create a Share Claim

Source: https://perkeep.org/doc/sharing

Use the 'pk put share' command to create a share claim for a specific blob. This command generates a claim blob that grants access.

```bash
pk put share --transitive sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d
```

--------------------------------

### Blob Stat API

Source: https://perkeep.org/doc/protocol/blob-stat

The blob stat API allows clients to check the existence and size of multiple blobs. The HTTP method can be GET or POST. GET is suitable for a small number of blobs, while POST is recommended for a larger number to avoid URL length limitations.

```APIDOC
## Blob Stat API

### Description
This endpoint allows clients to check the size and existence of multiple blobs. It can be accessed via GET or POST requests.

### Method
GET or POST

### Endpoint
`$blobRoot/camli/stat`

### Parameters
#### Query Parameters (for GET) or Form Values (for POST)
- **camliversion** (string) - Required - Version of Perkeep and/or stat protocol. Must be "1" for now.
- **blob<n>** (string) - Optional/Repeated - Blob reference (e.g., "sha1-..."). Must start at 1 and go up with no gaps. Servers may return 400 for too many blobs, but should support <= 1000.
- **maxwaitsec** (integer) - Optional - Maximum seconds the client is willing to wait for blobs. If the server supports long-polling, it may wait up to this time for blobs to become available.

### Request Example (GET)
```
GET /some-blob-root/camli/stat?camliversion=1&blob1=sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8 HTTP/1.1
Host: example.com
```

### Request Example (POST)
```
POST /some-blob-root/camli/stat HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: example.com

camliversion=1&
blob1=sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8&
blob2=sha1-abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd&
blob3=sha1-deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
```

### Response
#### Success Response (200)
- **stat** (array) - Required - Array of objects, each containing `blobRef` (string) and `size` (integer in bytes) for blobs the system has. Can be an empty list.
- **canLongPoll** (boolean) - Optional - Indicates if the server supports long polling. If not true, `maxwaitsec` is ignored.
```

--------------------------------

### Configure Perkeep with B2

Source: https://perkeep.org/doc/storage-examples

Add this line to your Perkeep server-config.json to enable Backblaze B2 storage. Replace 'accessKey', 'secretKey', and 'bucketName' with your B2 credentials and bucket details.

```json
"b2": "accessKey:secretKey:bucketName[/optional/dir][:hostname]"
```

--------------------------------

### Discovery Request with Accept Header

Source: https://perkeep.org/doc/protocol/discovery

Use this request format when the Accept header is preferred. The default path '/' is used if no specific path is configured.

```http
GET / HTTP1.1
Host: 127.0.0.1
Accept: text/x-camli-configuration


```

--------------------------------

### Get a blob

Source: https://perkeep.org/doc/protocol/blob-get

Retrieves the contents of a blob from the server. Returns 200 OK with blob contents if found, or 404 Not Found if the blob does not exist.

```APIDOC
## GET /camli/<blobref>

### Description
Retrieves the contents of a blob identified by its blobref.

### Method
GET

### Endpoint
/camli/<blobref>

### Parameters
#### Path Parameters
- **blobref** (string) - Required - The reference to the blob to retrieve.

### Response
#### Success Response (200)
- **Content-Type** (string) - The MIME type of the blob content.
- **Content-Length** (integer) - The size of the blob in bytes.

#### Response Example
```
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: <the blob length in bytes>

<the blob contents>
```

#### Error Response (404)
- **Not Found**

#### Response Example
```
HTTP/1.1 404 Not Found

```
```

--------------------------------

### Discovery Request with Query Parameter

Source: https://perkeep.org/doc/protocol/discovery

Use this request format when the Accept header is not explicitly set. Ensure the camli.mode parameter is set to 'config'.

```http
GET /some/user/?camli.mode=config HTTP/1.1
Host: camlihost.example.com


```

--------------------------------

### Configure Share Handler

Source: https://perkeep.org/doc/sharing

Ensure your Perkeep server configuration includes the 'shareHandler' set to true to enable sharing functionality.

```json
{
"shareHandler": true,

}
```

--------------------------------

### Basic 'or' and 'and' Predicate Grouping

Source: https://perkeep.org/doc/search-ui

Demonstrates combining predicates with 'or' and implicit 'and' logic. Spaces between predicates function as 'and'.

```text
tag:foo or is:pano tag:bar
```

--------------------------------

### Direct Blobserver Configuration

Source: https://perkeep.org/doc/client-config

Extends server configuration to point directly to a blobserver handler for optimized syncing.

```json
"servers": {
  ...
  "backup-bs": {
    "server": "https://some.remote.com/bs/",
    "auth": "userpass:pony:magic",
    "trustedCerts": ["ffc7730f4b"]
  }
}

```

--------------------------------

### Export Public Key with GPG

Source: https://perkeep.org/doc/json-signing

Export your public key to an ASCII-armored text file. This file will be used to generate the camliSigner blobref.

```bash
$ gpg --no-default-keyring --keyring example/test-keyring.gpg --secret-keyring example/test-secring.gpg \
      --export --armor 26F5ABDA > example/public-key.txt
```

--------------------------------

### Configure MySQL Indexer in Perkeep

Source: https://perkeep.org/doc/server-config

Modify your server configuration file to use MySQL for the indexer. Remove the 'sqlite' option and add 'dbname' and 'mysql' options.

```json
"dbname": "camliprod"

```

```json
"mysql": "foo@localhost:bar"

```

--------------------------------

### Configure Publisher Behind Reverse Proxy

Source: https://perkeep.org/doc/publishing/README

Configure the publisher server to run behind a reverse proxy. Specify listen, apiHost, and backendURL to manage communication between the publisher and the main Perkeepd process.

```json
{
  "publish": {
    "/pics/": {
	"apiHost": "http://localhost:3179/",
	"backendURL": "http://localhost:3155/",
	"listen": ":3155",
	... other settings from above ...
    }
  }

}
```

--------------------------------

### Configure Perkeep with S3

Source: https://perkeep.org/doc/storage-examples

Add this line to your Perkeep server-config.json to enable S3 storage. Replace 'accessKey', 'secretKey', and 'bucketName' with your AWS credentials and bucket details.

```json
"s3": "accessKey:secretKey:bucketName[/optional/dir][:hostname]"
```

--------------------------------

### Configure Perkeep with Google Cloud Storage

Source: https://perkeep.org/doc/storage-examples

Add this line to your Perkeep service-config.json to enable Google Cloud Storage. Replace 'clientId', 'clientSecret', 'refreshToken', and 'bucketName' with your GCS credentials and bucket details.

```json
"googlecloudstorage": "clientId:clientSecret:refreshToken:bucketName[/optional/dir]"
```

--------------------------------

### Access File Metadata via Share

Source: https://perkeep.org/doc/sharing

Access file metadata by including the share claim's blobRef in the 'via' parameter of a `/share/` request. This is the first step in accessing shared content.

```bash
$ curl http://perkeep.org:3179/share/sha1-0e5e60f367cc8156ae48198c496b2b2ebdf5313d?via=sha1-102758fb54521cb6540d256098e7c0f1625b33e3
```

--------------------------------

### Create a Share Claim

Source: https://perkeep.org/doc/schema/share

Use this JSON structure to create a share claim. Specify the authentication type, the target blob or search query, and whether the share should be transitive. The `camliSigner` and `claimDate` fields are typically populated by the Perkeep instance.

```json
{
"camliVersion": 1,

 // Type of authentication required to access the share. Currently only haveref
 // is supported, which means that anyone with the claim blobref can access.
 "authType": "haveref",

 "camliType": "claim",
 "camliSigner": "sha1-f2b0b7da718b97ce8c31591d8ed4645c777f3ef4",
 "claimDate": "2014-09-04T20:04:09.193945801Z",
 "claimType": "share",

 // The blob or search to share. Exactly one of these must be present. It is an
 // error to set neither or both.
 "target": "sha1-543fbdfdbcb1297af8a4dc7d299c0cb90e2bea0f",
 "search": <JSON object of type *search.SearchQuery>,

 // If true, anything recursively reachable from target or search is also
 // shared. Edges that are guaranteed to be followed for purposes of
 // reachability are:
 // - blobRef and bytesRef values of camliType="blob|file"
 // - members of camliType="static-set"
 // Currently reachability is implemented more loosely, but clients should not
 // depend on that.
 "transitive": false,

 <REQUIRED-JSON-SIGNATURE>
}

```

--------------------------------

### Calculate camliSigner Blobref

Source: https://perkeep.org/doc/json-signing

Calculate the SHA1 hash of the exported public key file to obtain the camliSigner blobref. This value is used to identify the public key for signature verification.

```bash
$ sha1sum example/public-key.txt
8616ebc5143efe038528c2ab8fa6582353805a7a
```

--------------------------------

### Matching Values with Spaces and Escaped Quotes

Source: https://perkeep.org/doc/search-ui

Illustrates how to match values containing spaces by enclosing them in double quotes. Also shows how to escape double quotes within a value using a backslash.

```text
attr:bar:"He said: \"Hi\""
```

--------------------------------

### Batch Blob Upload Request

Source: https://perkeep.org/doc/protocol/blob-upload

Use a POST request to the upload endpoint with multipart/form-data. Ensure each part has a 'name' matching the blobref, a 'Content-Type', and a 'filename'. The total request size should not exceed 32 MB.

```http
POST /$BLOB_SERVER_PATH_ROOT/camli/upload HTTP/1.1
Host: upload-server.example.com
Content-Type: multipart/form-data; boundary=randomboundaryXYZ

--randomboundaryXYZ
Content-Disposition: form-data; name="sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8"; filename="blob1"
Content-Type: application/octet-stream

(binary or text blob data)
--randomboundaryXYZ
Content-Disposition: form-data; name="sha1-deadbeefdeadbeefdeadbeefdeadbeefdeadbeef"; filename="blob2"
Content-Type: application/octet-stream

(binary or text blob data)
--randomboundaryXYZ--


```

--------------------------------

### Discovery Response JSON Structure

Source: https://perkeep.org/doc/protocol/discovery

The server responds with a JSON document containing Discovery values. This structure outlines the available configuration options.

```json
{
  "blobHashFuncs": [
    "sha1"
  ],
  "blobRoot": "/bs-and-maybe-also-index/",
  "directoryHelper": "/ui/tree/",
  "downloadHelper": "/ui/download/",
  "helpRoot": "/help/",
  "importerRoot": "/importer/",
  "jsonSignRoot": "/sighelper/",
  "ownerName": "The User Name",
  "publishRoots": {},
  "searchRoot": "/my-search/",
  "signing": {
    "publicKey": "/sighelper/camli/sha1-f72d9090b61b70ee6501cceacc9d81a0801d32f6",
    "publicKeyBlobRef": "sha1-f72d9090b61b70ee6501cceacc9d81a0801d32f6",
    "publicKeyId": "94DE83C46401800C",
    "signHandler": "/sighelper/camli/sig/sign",
    "verifyHandler": "/sighelper/camli/sig/verify"
  },
  "statusRoot": "/status/",
  "storageGeneration": "231ceff7a04a77cdf881b0422ea733334eee3b8f",
  "storageInitTime": "2012-11-30T03:34:47Z",
  "syncHandlers": [
    {
      "from": "/bs/",
      "to": "/index-mysql/",
      "toIndex": true
    },
    {
      "from": "/bs/",
      "to": "/sto-s3/",
      "toIndex": false
    }
  ],
  "thumbVersion": "2",
  "uiRoot": "/ui/",
  "uploadHelper": "/ui/?camli.mode=uploadhelper",
  "wsAuthToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

```

--------------------------------

### Claim JSON Structure for Multiple Operations

Source: https://perkeep.org/doc/schema/permanode

Demonstrates the JSON structure for a 'claim' node with 'multi' type, intended for atomically performing multiple attribute modifications on potentially different permanodes. This feature is not yet implemented.

```json
{
 "camliVersion": 1,
 "camliType": "claim",
 "claimType": "multi",
 "claimDate": "2013-02-24T17:20:03.9212Z",
 "claims": [
      {
       "claimType": "set-attribute",
       "permanode": "sha1-xxxxxx",
       "attribute": "foo",
       "value": "fooValue"
      },
      {
       "claimType": "add-attribute",
       "permanode": "sha1-yyyyy",
       "attribute": "tag",
       "value": "funny"
      }
 ],
 "camliSig": .........
}
```

--------------------------------

### Batch Upload Request

Source: https://perkeep.org/doc/protocol/blob-upload

This section details how to perform a batch upload of multiple blobs to the server. It specifies the endpoint, required parameters, and request format.

```APIDOC
## POST $BLOB_ROOT/camli/upload

### Description
Uploads multiple blobs in a single batch request.

### Method
POST

### Endpoint
$BLOB_ROOT/camli/upload

### Parameters
#### Request Body
- **multipart/form-data**: The request must be a multipart/form-data request.
  - **Content-Disposition**: Each part must have a `name` parameter which is the blobref (digest-hexhexhexhex) of the blob. The bytes must match the blobref.
  - **Content-Type**: Each part must have a `Content-Type` header. `application/octet-stream` is recommended.
  - **filename**: Each part must have a `filename` parameter in its `Content-Disposition`. This can be an increasing number or the blobref.

### Request Example
```http
POST /$BLOB_SERVER_PATH_ROOT/camli/upload HTTP/1.1
Host: upload-server.example.com
Content-Type: multipart/form-data; boundary=randomboundaryXYZ

--randomboundaryXYZ
Content-Disposition: form-data; name="sha1-9b03f7aca1ac60d40b5e570c34f79a3e07c918e8"; filename="blob1"
Content-Type: application/octet-stream

(binary or text blob data)
--randomboundaryXYZ
Content-Disposition: form-data; name="sha1-deadbeefdeadbeefdeadbeefdeadbeefdeadbeef"; filename="blob2"
Content-Type: application/octet-stream

(binary or text blob data)
--randomboundaryXYZ--
```

### Response
#### Success Response (200 or 303)
- **received** (array): An array of objects, each containing `blobRef` (string) and `size` (integer in bytes) for successfully saved blobs. Can be an empty list.
- **errorText** (string, optional): An error message for protocol errors not related to a specific blob.
```

--------------------------------

### Root Node Attributes for Publishing

Source: https://perkeep.org/doc/publishing/README

Define the necessary attributes for the root permanode when publishing content. The camliRoot must match the server configuration, and camliPath attributes map publish paths to permanodes.

```text
camliRoot = mypics // must match server-config.json
camilPath:foo = sha1-foo
camliPath:bar = sha1-bar


```

--------------------------------

### Fetch Share Claim Information

Source: https://perkeep.org/doc/sharing

Retrieve the details of a share claim using a curl request to the `/share/` endpoint. This demonstrates the claim's authentication type and target.

```bash
$ curl http://perkeep.org:3179/share/sha1-102758fb54521cb6540d256098e7c0f1625b33e3
```

--------------------------------

### Enumerate Blobs

Source: https://perkeep.org/doc/protocol/blob-enumerate

The /camli/enumerate-blobs endpoint enumerates all blobs that the server knows about. Blobs are returned in sorted order by digest type and value. This endpoint supports pagination using the 'after' parameter and limiting results with the 'limit' parameter. It also supports optional long-polling via the 'maxwaitsec' parameter.

```APIDOC
## GET /camli/enumerate-blobs

### Description
Enumerates all blobs that the server knows about, sorted by (digest_type, digest_value).

### Method
GET

### Endpoint
/camli/enumerate-blobs

### Parameters
#### Query Parameters
- **after** (string) - Optional - If provided, only blobs GREATER THAN this value are returned. Cannot be used in combination with 'maxwaitsec'.
- **limit** (integer) - Optional - Limit the number of returned blobrefs. The server may have its own lower limit.
- **maxwaitsec** (integer) - Optional - The maximum number of seconds the client is willing to wait for the arrival of blobs. Can't be used in combination with 'after'. The server's reply must include "canLongPoll" set to true if the server supports this feature.

### Request Example
```
GET /camli/enumerate-blobs?after=&limit= HTTP/1.1
Host: example.com
```

### Response
#### Success Response (200)
- **blobs** (array) - Required - Array of {"blobRef": BLOBREF, "size": INT_bytes}. Will be an empty list if no blobs are present.
- **continueAfter** (string) - Optional - If present, indicates there are more blobs after the provided blobref, which should be passed to the next request's "after" parameter.
- **canLongPoll** (boolean) - Optional - Set to true if the server supports long polling. If not true, the server ignores the client's "maxwaitsec" parameter.

#### Response Example
```json
{
  "blobs": [
    {"blobRef": "md5-acbd18db4cc2f85cedef654fccc4a4d8",
     "size": 3},
    {"blobRef": "sha1-0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33",
     "size": 3},
  ],
  "continueAfter": "sha1-0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33",
  "canLongPoll": true
}
```
```

--------------------------------

### Directory Schema Definition

Source: https://perkeep.org/doc/schema/directory

Defines the structure for a directory object in Perkeep. Ensure all required fields from common.md are included.

```json
{
"camliVersion": 1,
"camliType": "directory",

 //
 // INCLUDE ALL REQUIRED & ANY OPTIONAL FIELDS FROM common.md
 //

 // Required:
 "entries": "digalg-blobref-to-static-set"
}

```

--------------------------------

### Perkeep Replication Storage Configuration

Source: https://perkeep.org/doc/server-config

Configuration for a replica storage handler ('storage-replica') that forwards requests to multiple backends. This is used for replicating data to other Perkeep instances.

```json
/bsrepl/": {
        "handler": "storage-replica",
        "handlerArgs": {
            "backends": [
                "/bs/",
                "/r1/"
            ]
        }
    },

```

--------------------------------

### Create Detached Signature with GPG

Source: https://perkeep.org/doc/json-signing

Create an ASCII-armored detached signature of the JSON data. This signature will be appended to the JSON to create the signed document.

```bash
gpg --detach-sign --local-user=54F8A914 --armor \
    -o signing-before.camli.detachsig signing-before.camli
```
Tokens:
Raw