Exporting Metaproperties via the REST API

Summary

You may need a complete view of your metadata properties and taxonomy structure, whether to clean up unused or duplicate metadata, plan a portal restructuring, or maintain an internal reference for your team. The Bynder REST API makes this data self-serviceable: you can pull a full export on demand and automate the process to keep pace as your taxonomy evolves. Coverage and performance vary by use case; see Known Limitations below before relying on this method to export full metaproperty options.

If enabled, the Taxonomy Dashboards (Standard or Advanced Analytics) provide a Metaproperties view listing all metaproperties and their options, and an Automations view listing all configured automations, both of which are sortable and exportable to CSV directly from the UI. If your taxonomy includes very large metaproperties, or you need the full schema rather than just tagged values, the Taxonomy Dashboards can provide this, or you can submit a support ticket to learn more about export options.

Who?

  • Requires Portal Admin access to create a Permanent Token.
  • Best suited for System Administrators or developers who are comfortable making API calls or running a simple script.

Why?

  • Provides an on-demand export of metaproperty and taxonomy data without a support ticket or paid export service.
  • Can be automated and re-run at any time, which is useful when your taxonomy changes frequently.
  • Supports bi-directional workflows: the API can also be used to write custom metadata tags back into Bynder metaproperties, enabling metadata pipelines between Bynder and other systems.
  • Gives you full control over the output format, since the API returns structured data you can convert as needed.

Known Limitations

  • Large metaproperty option sets: Calling GET /api/v4/metaproperties/ with options=true on a very large metaproperty (for example, one with 600,000+ options) can cause performance issues. Offset-based pagination becomes increasingly heavy on the database as it progresses: request times slow from approximately 0.3s at the start to over 8s after 500,000 records, and the request can eventually fail. Use options=false and fetch options separately via GET /api/1/taxonomy/metaproperties/{metapropertyId}/options instead.
  • 403 on the options endpoint: A 403 response on the options endpoint has been reported even when the token has all :read scopes. This is a known issue; check with Bynder support rather than assuming a scope/permissions error.
  • Rate limit: The API is limited to 4,500 requests per IP address per 5-minute interval. Factor this into any automated or bulk export process.
  • Not a substitute for the metadata CSV export: The CSV metadata export available when downloading assets only includes metadata values currently tagged on the selected assets. It does not export the full metaproperty schema, the list of configured options for each metaproperty, or access rights/permissions settings.

How?

Available Endpoints

Endpoint Purpose
GET /api/v4/metaproperties/ Retrieves metaproperties
GET /api/1/taxonomy/metaproperties Lists metaproperties
GET /api/1/taxonomy/metaproperties/{metapropertyId}/options Retrieves options for a specific metaproperty

Option A: Export the full metaproperty schema (smaller taxonomies)

  1. Generate a Permanent Token.
    • Navigate to Settings > Advanced Settings > Portal Settings and click Permanent Tokens.
    • Click Add new token and enter a description.
    • Assign a user to the token, and select the appropriate scope for the resource you need to access. Confirm the exact scope label in the Permanent Tokens article or current portal UI, as this was not independently confirmed for this article.
  2. Retrieve the list of metaproperties.
    • Use GET /api/v4/metaproperties/ or GET /api/1/taxonomy/metaproperties (see table above).
    • For large taxonomies, call GET /api/v4/metaproperties/ with options=false rather than options=true. Requesting all options inline can cause performance issues on large metaproperties.
  3. Retrieve the options for each metaproperty separately.
    • Use GET /api/1/taxonomy/metaproperties/{metapropertyId}/options, substituting the ID of each metaproperty from step 2.
    • Known issue: A 403 response on this endpoint has been reported even when the token has all :read scopes. If you hit this, check with Bynder support before assuming it's a permissions misconfiguration on your end.
  4. Review the response.
    • The response returns each metaproperty and its options, including labels, IDs, and configuration details such as zone restrictions and dependencies.
  5. Convert the output to your required format.
    • Use a script or spreadsheet tool to convert the response into CSV or another format, if needed.

Option B: Query assets by metaproperty value (taxonomy validation)

  1. Use the Permanent Token generated in Option A, step 1.
  2. Query the Assets endpoint filtered by a specific metaproperty value.
  3. Export the results to validate which assets are tagged with a given value, useful for taxonomy clean-up or validation workflows rather than a full schema export.

Option C: Export analytics data via the API

All analytics data, including asset usage, user activity, metadata, and lifecycle events (downloads, views, uploads, metadata changes), is accessible via the REST API for export to a data warehouse. Raw event data has 1 year of history available by default; additional history is available on request.

Note: Field names, available attributes, and endpoint behavior are subject to the current API version. Refer to the API documentation linked below to confirm the latest response schema and endpoint paths before building an automated process, and account for the rate limit noted above.

Related Articles

Understanding The Taxonomy Dashboards

How To Import And Export Assets With SFTP Or S3

How To Create Permanent API Tokens For Integrations

 

 

Updated