Export your catalog

This guide copies the original bytes of every feed that matches a filter into a storage resource, where any tool that reads that storage can read them. You need a signed-in account with xixo:catalog:write, and at least one attached resource that serves storage. See resources and attaching a resource.

What an export writes

An export starts an export run and queues ExportItemsJob on the export queue. The job walks every feed that has at least one reference and matches the filter. For each one it takes an original reference held on some other resource, downloads the bytes, and uploads them to the destination.

• Each file is written at <source resource key>/<locator key>. A file from the resource photos at 2024/beach.jpg lands at photos/2024/beach.jpg.
• In an s3 resource, the bucket is the resource’s key, and the path is the object key from the bucket’s root. The resource’s prefix does not apply.
• In a filesystem resource, the path is relative to the resource’s root, which sits inside the tenant’s directory under XIXO_FILESYSTEM_ROOTS.
• Only original bytes are copied. Previews, thumbnails, analyses, titles, tags, and edges stay in xixo.
• Each copy is recorded as another reference on its feed, so the feed lists the destination among its locations.
• A feed with no original reference, or whose only original is already on the destination, is skipped.
• Exporting again to the same destination skips every copy whose source version has not changed. A changed source is written over the existing copy at the same path.

Export from the app

1. Open the catalog. To export part of it, pick a type or type a search in the bar first. The dialog starts with both filled in.
2. Open the More menu (the three dots) and choose Export these….
3. Under Write them to, pick a storage resource. Left empty, the export goes to the tenant’s default storage. If the tenant has none, Export stays disabled until you pick one.
4. Narrow it with Of type and Matching if you want. Matching takes the same search you would type in the bar. With both empty, every referenced feed is exported.
5. Choose Export. The dialog closes and says the export is running.
6. The export goes on as a run. It is queued, then running, and finishes done, failed, cancelled, or gated. Follow it and read its log over GraphQL.

Export over GraphQL

exportFeeds takes an optional destinationId, query, type, and resourceId, and needs xixo:catalog:write. resourceId limits the export to feeds with a reference on that resource. See the GraphQL reference.

1. Find the destination’s id. This query needs xixo:resources:read.

   query {
     resources { id key capabilities defaultStorage }
   }

2. Start the export:

   mutation {
     exportFeeds(input: { destinationId: "12", type: "xixo:file", query: "invoices 2025" }) {
       run { id status }
     }
   }

3. Poll the run until status is done or failed:

   query {
     run(id: "34") { status processed error logs }
   }

To stop it, call cancelRun with the run’s id.

Export over MCP

The resource tool exports with do: "export". The token needs xixo:resources:read and xixo:resources:command. See MCP and scopes.

1. Call resource with no arguments to list resources, and pick one whose capabilities include storage.

2. Call it with that resource’s key:

   {
     "key": "archive",
     "do": "export",
     "input": { "type": "xixo:file", "query": "invoices 2025" }
   }

   input accepts query, type, mime, tag, resource_id, folder, since, and before. The call answers with the run’s id and status.

3. Follow it with do: "runs" on the same key, and stop it with do: "cancel" and input: { "id": "<run id>" }.

Each token can start XIXO_RUN_BUDGET runs an hour through MCP (20 by default). Syncs and exports share the budget.

Fetch the files

Read the destination with any client for its type.

• For s3, list or copy the bucket with the provider’s tools, for example aws s3 sync s3://archive ./archive --endpoint-url https://s3.example.com.
• For filesystem, copy the directory from the server. In the example Compose project it is inside the files volume, at /data/files/<tenant>/.
• For webdav, use any WebDAV client.

Move the files to another xixo

1. Export to an s3 or webdav resource that the other deployment can reach.
2. In the other xixo, attach the same bucket or share as a resource.
3. Sync it. Every file it finds becomes a reference on a feed there, and is analyzed. See adding.

Titles, tags, edges, and analyses are not part of the export. The new catalog analyzes the files again.

If it doesn’t work

• “this tenant has no default storage resource”: pick a destination, or make a storage resource the default with Take drops in its ⋯ menu on Resources.
• “<key> is not storage”: the destination does not serve storage. Pick an s3, filesystem, or webdav resource.
• The run ends gated: an export gate is closed for the tenant, or XIXO_ITERATORS_DISABLED is set on the server.
• The run ends failed: the destination refused a write. The job retries five times with a growing wait before it fails the run, and the error is on the run. Check the destination from Resources.
• The run stays queued: no worker is running the export queue. See self-hosting.
• “this token has started N runs in the last hour”: the MCP run budget is spent. The count resets at the start of each clock hour. An operator can raise XIXO_RUN_BUDGET, and 0 removes the limit.