You are using a browser that is not supported.

API Documentation

How to Authenticate

Some products and releases may require authentication to access or modify. Your Pivotal Network API Token can be found on your Edit Profile page. This API token should be used in the Authorization header of the request. The Authentication API can be used to test that you are using your authorization token correctly.

Request headers

HEADER          VALUE
------          -----
Accept          application/json
Content-Type    application/json
Authorization   Token <API Token>

Example cURL request

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token <API Token>" -X GET https://network.pivotal.io/api/v2/authentication

GET /api/v2/authentication

  • Tests that your authorization token is valid
    • returns 200 if successful
    • returns 401 if user could not be authenticated

Example

Request


GET /api/v2/authentication HTTP/1.1
Accept: application/json
Authorization: Token valid-token
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: no-cache
Content-Length: 0
Content-Type: application/json

GET /api/v2/products/:product_slug/releases/:release_id/product_files/:id/download

  • Creates a download link for a release's product file. The user can utilize this link to download the file.
    • redirects to a unique file download URL
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to download files from this release
    • returns 404 if the product or release cannot be found
    • returns 451 if user has not accepted the current EULA for this release
  • Authentication required
  • POST supported for backwards compatibility

Example wget request

wget -O "<filename>" --header="Authorization: Token <API Token>" https://network.pivotal.io/api/v2/products/<product-id>/releases/<release-id>/product_files/<product-file-id>/download

Example

Request


GET /api/v2/products/product-2/releases/1/product_files/1/download HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-1"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 302
Cache-Control: no-cache
Content-Length: 128
Content-Type: text/html; charset=utf-8
Location: http://localhost/cloud_front_stub/product-2/product-file-1.txt


<html><body>You are being <a href="http://localhost/cloud_front_stub/product-2/product-file-1.txt">redirected</a>.</body></html>

GET /api/v2/products/:product_slug/releases/:release_id/product_files/:id/signature_file_download

  • Creates a signature file download link for a release's product file. The user can utilize this link to download the signature file.
    • redirects to a unique signature file download URL
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to download files from this release
    • returns 404 if the product or release cannot be found, or the product file does not have a signature
  • Authentication required
  • POST supported for backwards compatibility

Example wget request

wget -O "<filename>" --header="Authorization: Token <API Token>" https://network.pivotal.io/api/v2/products/<product-id>/releases/<release-id>/product_files/<product-file-id>/signature_file_download

Example

Request


GET /api/v2/products/product-3/releases/2/product_files/2/signature_file_download HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-2"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 302
Cache-Control: no-cache
Content-Length: 132
Content-Type: text/html; charset=utf-8
Location: http://localhost/cloud_front_stub/product-3/product-file-2.txt.sig


<html><body>You are being <a href="http://localhost/cloud_front_stub/product-3/product-file-2.txt.sig">redirected</a>.</body></html>

POST /api/v2/products/:product_slug/releases/:release_id/eula_acceptance

  • Accept a release's End User License Agreement (EULA).
    • returns 200 if the EULA is accepted
    • returns 401 if the user could not be authenticated
    • returns 404 if the product or release cannot be found
  • Authentication required

Example

Request


POST /api/v2/products/product-26/releases/35/eula_acceptance HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-16"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 100
Content-Type: application/json; charset=utf-8
ETag: W/"520ec379039520d57c92068cb0aa3b3a"


{
  "accepted_at": "2017-02-09",
  "_links": {
    "eula": {
      "href": "https://network.pivotal.io/api/v2/eulas/28"
    }
  }
}

GET /api/v2/eulas

  • Returns list of available End User License Agreements (EULAs).
    • returns 200 if successful
  • No authentication required.

Example

Request


GET /api/v2/eulas HTTP/1.1
Accept: application/json
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=300, public
Content-Length: 277
Content-Type: application/json; charset=utf-8
Date: Thu, 09 Feb 2017 15:16:11 GMT
ETag: W/"7250d1e3f0ddb76bd2c635c7cd784564"


{
  "eulas": [
    {
      "id": 3,
      "slug": "pivotal_software_eula",
      "content": "This is the context of the legal document.",
      "name": "Pivotal Software EULA",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/eulas/3"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/eulas"
    }
  }
}

GET /api/v2/eulas/:slug

  • Returns the latest version of the requested End User License Agreement (EULA).
    • returns 200 if the EULA is found
    • returns 404 if the EULA cannot be found
  • No authentication required.

Example

Request


GET /api/v2/eulas/pivotal_software_eula HTTP/1.1
Accept: application/json
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=300, public
Content-Length: 196
Content-Type: application/json; charset=utf-8
Date: Thu, 09 Feb 2017 15:16:12 GMT
ETag: W/"d1d1bf3fa04c2e1c1afad3befc7f1955"


{
  "id": 4,
  "slug": "pivotal_software_eula",
  "content": "This is the context of the legal document.",
  "name": "Pivotal Software EULA",
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/eulas/4"
    }
  }
}

GET /api/v2/eulas/:id

  • Get a single End User License Agreement (EULA).
    • returns 200 if the EULA is found
    • returns 404 if the EULA cannot not be found
  • No authentication required.

Example

Request


GET /api/v2/eulas/5 HTTP/1.1
Accept: application/json
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=300, public
Content-Length: 196
Content-Type: application/json; charset=utf-8
Date: Thu, 09 Feb 2017 15:16:12 GMT
ETag: W/"6f256cfae4da4a00d9028e5e1102fe2f"


{
  "id": 5,
  "slug": "pivotal_software_eula",
  "content": "This is the context of the legal document.",
  "name": "Pivotal Software EULA",
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/eulas/5"
    }
  }
}

GET /api/v2/users/countries_states

  • List of non-excluded countries and their states

Example

Request


GET /api/v2/users/countries_states HTTP/1.1
Accept: application/json
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 968
Content-Type: application/json; charset=utf-8
ETag: W/"685f07153addd96e75279ef9242c4ef5"


[
  {
    "country": "Togo",
    "country_code": "TG",
    "states": [
      {
        "state": "Région du Centre",
        "state_code": "C"
      },
      {
        "state": "Région de la Kara",
        "state_code": "K"
      },
      {
        "state": "Région Maritime",
        "state_code": "M"
      },
      {
        "state": "Région des Plateaux",
        "state_code": "P"
      },
      {
        "state": "Région des Savannes",
        "state_code": "S"
      }
    ]
  },
  {
    "country": "Haiti",
    "country_code": "HT",
    "states": [
      {
        "state": "Artibonite",
        "state_code": "AR"
      },
      {
        "state": "Centre",
        "state_code": "CE"
      },
      {
        "state": "Grande-Anse",
        "state_code": "GA"
      },
      {
        "state": "Nord",
        "state_code": "ND"
      },
      {
        "state": "Nord-Est",
        "state_code": "NE"
      },
      {
        "state": "Nord-Ouest",
        "state_code": "NO"
      },
      {
        "state": "Ouest",
        "state_code": "OU"
      },
      {
        "state": "Sud",
        "state_code": "SD"
      },
      {
        "state": "Sud-Est",
        "state_code": "SE"
      }
    ]
  },
  {
    "country": "Djibouti",
    "country_code": "DJ",
    "states": [
      {
        "state": "Arta",
        "state_code": "AR"
      },
      {
        "state": "Ali Sabieh",
        "state_code": "AS"
      },
      {
        "state": "Dikhil",
        "state_code": "DI"
      },
      {
        "state": "Djibouti",
        "state_code": "DJ"
      },
      {
        "state": "Obock",
        "state_code": "OB"
      },
      {
        "state": "Tadjourah",
        "state_code": "TA"
      }
    ]
  }
]

POST /api/v2/users

  • Signup Pivnet user, creating UAA user if required
    • returns 200, user info except password and including API Token if successful
    • returns 400 if user info is missing
    • returns 422 if there are validation errors, such as country-state mismatch
  • No authentication required.
  • Country and state codes can be fetched via the GET /api/v2/users/countries_states endpoint.

Example

Request


POST /api/v2/users HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-55"
Content-Length: 292
Content-Type: application/json
Host: network.pivotal.io


{
  "user": {
    "first_name": "first",
    "last_name": "last",
    "country_code": "CA",
    "state_code": "ON",
    "organization": "some-organization",
    "title": "honcho",
    "phone_number": "+1 555-555-5555",
    "government_employee": false,
    "email_address": "flast@pivotal.io",
    "password": "some-password",
    "accepted_terms_of_use": true
  }
}

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 270
Content-Type: application/json; charset=utf-8
ETag: W/"dc0527dbf6bd1c6fd14b47edbf1fc848"


{
  "id": 64,
  "first_name": "first",
  "last_name": "last",
  "country_code": "CA",
  "state_code": "ON",
  "organization": "some-organization",
  "title": "honcho",
  "phone_number": "+1 555-555-5555",
  "government_employee": false,
  "email_address": "flast@pivotal.io",
  "api_token": "qz8VfvAsaDiz6gyVtD1E"
}

GET /api/v2/user_groups

  • Lists all user groups
    • returns 401 if you do not have a valid API token
    • returns 403 if you do not have access to user groups
  • Authentication required

Example

Request


GET /api/v2/user_groups HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-39"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 262
Content-Type: application/json; charset=utf-8
ETag: W/"b6b099b5dd8c81c3587349b8a27cd8ae"


{
  "user_groups": [
    {
      "id": 4,
      "name": "Product X Users",
      "description": "users for the next version of Product X"
    },
    {
      "id": 5,
      "name": "Fancy Users",
      "description": "Limit access to fancy people only"
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/user_groups"
    }
  }
}

GET /api/v2/user_groups/:id

  • Returns a specific user group
    • returns 200 if the user group is found
    • returns 401 if you do not have a valid API token
    • returns 404 if the user group cannot be found
  • Authentication required

Example

Request


GET /api/v2/user_groups/6 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-42"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 368
Content-Type: application/json; charset=utf-8
ETag: W/"24d7b7160df515344641f1e59ebef15d"


{
  "id": 6,
  "name": "VIP Users",
  "description": "Important users with early access to next version of Product X",
  "members": [
    "Joe Schmoe <alpha@example.net>",
    "Joe Schmoe <bravo@example.net>",
    "Joe Schmoe <charlie@example.net>",
    "Joe Schmoe <user@example.net>"
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/user_groups/6"
    }
  }
}

POST /api/v2/user_groups

  • Create a new user group with yourself as an admin member
    • returns 201 if the user group is created
    • the Location header will point to the newly created user group
    • returns 400 if there is no user_group key in the request payload
    • returns 401 if you do not have a valid API token
    • returns 403 if user does not have access to create user groups
    • returns 422 if the user group cannot be created due to invalid request data
  • Authentication required
  • NOTE: Users that do not already have an account on Pivotal Network will not be added to the user group

Example

Request


POST /api/v2/user_groups HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-46"
Content-Length: 164
Content-Type: application/json
Host: network.pivotal.io


{
  "user_group": {
    "name": "Brand New User Group",
    "description": "These users have early access to Products X and Y",
    "members": [
      "alpha@example.net",
      "bravo@example.net"
    ]
  }
}

Response


HTTP/1.1 201
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 321
Content-Type: application/json; charset=utf-8
ETag: W/"4e329b8e13a68110e31586e3aa1de447"
Location: https://network.pivotal.io/api/v2/user_groups/7


{
  "id": 7,
  "name": "Brand New User Group",
  "description": "These users have early access to Products X and Y",
  "members": [
    "Joe Schmoe <alpha@example.net>",
    "Joe Schmoe <bravo@example.net>",
    "Joe Schmoe <user@example.net>"
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/user_groups/7"
    }
  }
}

PATCH /api/v2/user_groups/:user_group_id

  • Update an existing user group that you manage. Only the keys you provide will be modified.
    • returns 200 if the user group is updated
    • returns 400 if there is no user_group key in the request payload
    • returns 401 if you do not have a valid API token
    • returns 403 if you do not have access to update this user group
    • returns 404 if the user group cannot be found
    • returns 422 if the user group cannot be updated due to invalid request data
  • Authentication required
  • The members key cannot be updated by this method. Please use /api/v2/user_groups/:user_group_id/add_member or /api/v2/user_groups/:user_group_id/remove_member.

Example

Request


PATCH /api/v2/user_groups/8 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-49"
Content-Length: 58
Content-Type: application/json
Host: network.pivotal.io


{
  "user_group": {
    "name": "name",
    "description": "description"
  }
}

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 196
Content-Type: application/json; charset=utf-8
ETag: W/"2e508b399a183caa6bd1d9dae83e9448"


{
  "user_group": {
    "id": 8,
    "name": "name",
    "description": "description",
    "members": [
      "Joe Schmoe <user@example.net>"
    ],
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/user_groups/8"
      }
    }
  }
}

PATCH /api/v2/user_groups/:user_group_id/add_member

  • Add a new member to an existing user group that you manage
    • Required fields: email
    • Optional fields: admin. Set to true if you would like this new member to also manage the user group.
    • returns 200 if the member has been added to the user group (includes when the user was already a member)
    • returns 400 if there is no member or email key in the request payload
    • returns 401 if you do not have a valid API token
    • returns 403 if you do not have access to modify this user group
    • returns 404 if the user group cannot be found or if there is no Pivotal Network account for the requested email address
  • Authentication required
  • NOTE: Users that do not already have an account on Pivotal Network will not be added to the user group

Example

Request


PATCH /api/v2/user_groups/9/add_member HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-50"
Content-Length: 59
Content-Type: application/json
Host: network.pivotal.io


{
  "member": {
    "email": "member_user@example.com",
    "admin": true
  }
}

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 263
Content-Type: application/json; charset=utf-8
ETag: W/"1389bc2a14a2d51ffb54aaa66b2156f5"


{
  "user_group": {
    "id": 9,
    "name": "Group Name #3",
    "description": "Group Description #5",
    "members": [
      "Joe Schmoe <member_user@example.com>",
      "Joe Schmoe <user@example.net>"
    ],
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/user_groups/9"
      }
    }
  }
}

PATCH /api/v2/user_groups/:user_group_id/remove_member

  • Remove a member from an existing user group that you manage
    • returns 200 if the member has been removed from the user group
    • returns 400 if there is no member or email key in the request payload
    • returns 401 if you do not have a valid API token
    • returns 403 if you do not have access to modify this user group
    • returns 404 if the user group cannot be found or if there is no Pivotal Network account for the requested email address
  • Authentication required

Example

Request


PATCH /api/v2/user_groups/10/remove_member HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-52"
Content-Length: 46
Content-Type: application/json
Host: network.pivotal.io


{
  "member": {
    "email": "update_user@example.com"
  }
}

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 216
Content-Type: application/json; charset=utf-8
ETag: W/"af44fff2dfb62a57e257c025046c9be8"


{
  "user_group": {
    "id": 10,
    "name": "Group Name #4",
    "description": "Group Description #6",
    "members": [
      "Joe Schmoe <user@example.net>"
    ],
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/user_groups/10"
      }
    }
  }
}

DELETE /api/v2/user_groups/:user_group_id

  • Delete a user group that you manage
    • returns 204 if the user group has been deleted
    • returns 401 if you do not have a valid API token
    • returns 403 if you do not have access to delete this user group
    • returns 404 if the user group cannot be found
  • Authentication required

Example

Request


DELETE /api/v2/user_groups/11 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-54"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 204
Cache-Control: no-cache

GET /api/v2/products

  • Returns a list of products
    • returns 200 if successful
    • returns 401 if user could not be authenticated
  • Authentication optional, but required to view products not publicly available

Example

Request


GET /api/v2/products HTTP/1.1
Accept: application/json
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 87
Content-Type: application/json; charset=utf-8
ETag: W/"fbcfb6bd3789f1ffab8a5d0d52984540"


{
  "products": [

  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products"
    }
  }
}

GET /api/v2/products/:product_slug

  • Returns a specific product
    • returns 200 if product is found
    • returns 401 if user could not be authenticated
    • returns 404 if product cannot be found or user is not permitted to view
    • returns 410 if product no longer exists but user was permitted to view
  • Authentication optional, but required to view products not publicly available

Example

Request


GET /api/v2/products/my-product-slug HTTP/1.1
Accept: application/json
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 643
Content-Type: application/json; charset=utf-8
ETag: W/"c95727bdf11477e8a67aa0945c7057b5"


{
  "id": 23,
  "slug": "my-product-slug",
  "name": "Product 23",
  "logo_url": "http://localhost/cloud_front_stub/assets/images/p-logo.png",
  "category": "Data",
  "description": "Description",
  "feature_list": [
    "Features.",
    "More features.",
    "Zero bugs."
  ],
  "docs_url": "https://docs.example.com",
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/my-product-slug"
    },
    "releases": {
      "href": "https://network.pivotal.io/api/v2/products/my-product-slug/releases"
    },
    "product_files": {
      "href": "https://network.pivotal.io/api/v2/products/my-product-slug/product_files"
    },
    "file_groups": {
      "href": "https://network.pivotal.io/api/v2/products/my-product-slug/file_groups"
    }
  }
}

PATCH /api/v2/products/:product_slug/release_sort_order

  • Change the release display order for the specified product
  • The ids array must contain exactly the release ids associated with this product
    • returns 204 if the release sort order is updated
    • returns 400 if there is no releases key in the request payload
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to update the release sort order for this product
    • returns 404 if the product cannot be found
    • returns 422 if the release sort order cannot be updated due to invalid data
  • Authentication required

Example

Request


PATCH /api/v2/products/pivotal-cf/release_sort_order HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-8"
Content-Length: 31
Content-Type: application/json
Host: network.pivotal.io


{
  "releases": {
    "ids": [
      18,
      19,
      20
    ]
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

GET /api/v2/products/:product_slug/product_files

  • Lists files associated with the specified product
    • returns 200 if the product is found
    • returns 401 if you do not have a valid API token
    • returns 403 if the user is not permissioned to view product files
    • returns 404 if the product cannot be found
  • Authentication optional, but required to view products not available to public

Example

Request


GET /api/v2/products/your-product-slug/product_files HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-3"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 565
Content-Type: application/json; charset=utf-8
ETag: W/"265ea2fd05ba3efd19fe039e848e0434"


{
  "product_files": [
    {
      "id": 11,
      "aws_object_key": "product-11/pivnet-1.0.0a.bz2",
      "file_version": "1.0.0",
      "name": "PivNet (packaged)",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/your-product-slug/product_files/11"
        }
      }
    },
    {
      "id": 10,
      "aws_object_key": "product-11/really_great_software.exe",
      "file_version": "1.0.0",
      "name": "Really Great Software",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/your-product-slug/product_files/10"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/your-product-slug/product_files"
    }
  }
}

GET /api/v2/products/:product_slug/product_files/:id

  • Show a product file for a product
    • returns 200 if the product file is found
    • returns 401 if the user could not be authenticated
    • returns 403 if the user is not permissioned to view the product file
    • returns 404 if the product or the product file cannot be found
  • Authentication required

Example

Request


GET /api/v2/products/your-product-slug/product_files/12 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-4"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 659
Content-Type: application/json; charset=utf-8
ETag: W/"240471df585545f0d9a76b130cfb927c"


{
  "product_file": {
    "id": 12,
    "aws_object_key": "product-13/pcf-1.1.0.0.ova",
    "description": "OVA Release of Pivotal CF v1.1.0.0",
    "docs_url": "http://zombo.com",
    "file_transfer_status": "failed_to_transfer",
    "file_type": "Software",
    "file_version": "1.1.0.0",
    "has_signature_file": false,
    "included_files": [
      "pcf-server.exe",
      "pcf-client.exe"
    ],
    "md5": "c705c6e6339ebb3417ed1f118efbe620",
    "name": "Pivotal CF",
    "platforms": [
      "Android",
      "AWS",
      "Apt-Get"
    ],
    "ready_to_serve": false,
    "released_at": "2015-12-31",
    "size": 1024,
    "system_requirements": [
      "Windows Vista",
      "Microsoft Office 1995"
    ],
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/your-product-slug/product_files/12"
      }
    }
  }
}

POST /api/v2/products/:product_slug/product_files

  • Creates a product file associated with the specified product
    • Required fields: name, aws_object_key, file_type, file_version, md5
    • Optional fields: description, docs_url, has_signature_file, included_files, platforms, released_at (defaults to today's date), system_requirements
    • Valid file types: Software, Documentation, Open Source License
    • Valid platforms: Android, AWS, Apt-Get, BOSH, Brew, CentOS, Chef, GVM, Generic, Google Compute Engine, iOS, Linux, MSI, Maven Repo, Microsoft Hyper-V, OS X, OVM, OpenStack, Oracle Linux, Pivotal CF, Puppet, RHEL, RedHat KVM, SLES, Solaris, Ubuntu, VHCS, VM, Virtual Appliance, Windows, Windows Server, Yum, vSphere
    • returns 201 if the product file is successfully created
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if you do not have a valid API token
    • returns 403 if user does not have access to create product files on the product
    • returns 404 if the product cannot be found
    • returns 422 if the product file cannot be created due to invalid product file data
  • Authentication required

Example

Request


POST /api/v2/products/your-product-slug/product_files HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-5"
Content-Length: 438
Content-Type: application/json
Host: network.pivotal.io


{
  "product_file": {
    "aws_object_key": "product-15/pcf-1.1.0.0.ova",
    "description": "OVA Release of Pivotal CF v1.1.0.0",
    "docs_url": "http://zombo.com",
    "file_type": "Software",
    "file_version": "1.1.0.0",
    "included_files": [
      "pcf-server.exe",
      "pcf-client.exe"
    ],
    "md5": "c705c6e6339ebb3417ed1f118efbe620",
    "name": "Pivotal CF",
    "platforms": [
      "Android",
      "AWS",
      "Apt-Get"
    ],
    "released_at": "2015/12/31",
    "system_requirements": [
      "Windows Vista",
      "Microsoft Office 1995"
    ]
  }
}

Response


HTTP/1.1 201
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 652
Content-Type: application/json; charset=utf-8
ETag: W/"a53a020d44a87ec9a1f1b1e394b4e35f"


{
  "product_file": {
    "id": 13,
    "aws_object_key": "product-15/pcf-1.1.0.0.ova",
    "description": "OVA Release of Pivotal CF v1.1.0.0",
    "docs_url": "http://zombo.com",
    "file_transfer_status": "in_progress",
    "file_type": "Software",
    "file_version": "1.1.0.0",
    "has_signature_file": false,
    "included_files": [
      "pcf-server.exe",
      "pcf-client.exe"
    ],
    "md5": "c705c6e6339ebb3417ed1f118efbe620",
    "name": "Pivotal CF",
    "platforms": [
      "Android",
      "AWS",
      "Apt-Get"
    ],
    "ready_to_serve": false,
    "released_at": "2015-12-31",
    "size": 1024,
    "system_requirements": [
      "Windows Vista",
      "Microsoft Office 1995"
    ],
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/your-product-slug/product_files/13"
      }
    }
  }
}

PATCH /api/v2/products/:product_slug/product_files/:id

  • Updates an existing product file for the specified product
    • Valid file types: Software, Documentation, Open Source License
    • Valid platforms: Android, AWS, Apt-Get, BOSH, Brew, CentOS, Chef, GVM, Generic, Google Compute Engine, iOS, Linux, MSI, Maven Repo, Microsoft Hyper-V, OS X, OVM, OpenStack, Oracle Linux, Pivotal CF, Puppet, RHEL, RedHat KVM, SLES, Solaris, Ubuntu, VHCS, VM, Virtual Appliance, Windows, Windows Server, Yum, vSphere
    • returns 200 if the product file is updated
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if the user could not be authenticated
    • returns 403 if the user does not have access to update the product
    • returns 404 if the product or the product file cannot be found
    • returns 422 if the product file cannot be due to invalid product file data
  • Authentication required

Example

Request


PATCH /api/v2/products/your-product-slug/product_files/14 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-6"
Content-Length: 68
Content-Type: application/json
Host: network.pivotal.io


{
  "product_file": {
    "description": "new description",
    "name": "Law Blog"
  }
}

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 510
Content-Type: application/json; charset=utf-8
ETag: W/"544a9ed729faf209915cf6267f50ed2d"


{
  "product_file": {
    "id": 14,
    "aws_object_key": "product-17/path/to/key",
    "description": "new description",
    "docs_url": null,
    "file_transfer_status": "complete",
    "file_type": "Software",
    "file_version": "1.0.0",
    "has_signature_file": false,
    "included_files": [

    ],
    "md5": "c705c6e6339ebb3417ed1f118efbe620",
    "name": "Law Blog",
    "platforms": [

    ],
    "ready_to_serve": true,
    "released_at": "2017-02-09",
    "size": 1024,
    "system_requirements": [

    ],
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/your-product-slug/product_files/14"
      }
    }
  }
}

DELETE /api/v2/products/:product_slug/product_files/:id

  • Deletes the specified product file
    • returns 200 if the product file is deleted
    • returns 401 if the user could not be authenticated
    • returns 403 if the user does not have access to delete this product file
    • returns 404 if the product or the product file cannot be found
  • Authentication required

Example

Request


DELETE /api/v2/products/your-product-slug/product_files/15 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-7"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 532
Content-Type: application/json; charset=utf-8
ETag: W/"4c6b5c415555326bd2e9103e4228db4a"


{
  "product_file": {
    "id": 15,
    "aws_object_key": "product-19/product-file-11.txt",
    "description": "product description 13",
    "docs_url": null,
    "file_transfer_status": "complete",
    "file_type": "Software",
    "file_version": "1.0.0",
    "has_signature_file": false,
    "included_files": [

    ],
    "md5": "c705c6e6339ebb3417ed1f118efbe620",
    "name": "Product File 11",
    "platforms": [

    ],
    "ready_to_serve": true,
    "released_at": "2017-02-09",
    "size": 1024,
    "system_requirements": [

    ],
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/your-product-slug/product_files/15"
      }
    }
  }
}

GET /api/v2/products/:product_slug/file_groups

  • List file groups for a product
    • returns 200 if the product's file groups are found
    • returns 401 if the user could not be authenticated
    • returns 403 if the user is not permissioned to view file groups
    • returns 404 if the product is not found
  • Authentication required

Example

Request


GET /api/v2/products/product-4/file_groups HTTP/1.1
Accept: application/json
Authorization: Token token="validtoken"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 458
Content-Type: application/json; charset=utf-8
ETag: W/"1f7572f87de8313adeca8b66a7d432c5"


{
  "file_groups": [
    {
      "id": 1,
      "name": "File Group 1",
      "product_files": [
        {
          "id": 3,
          "aws_object_key": "product-4/product-file-3.txt",
          "file_version": "1.0.0",
          "name": "Product File 3",
          "_links": {
            "self": {
              "href": "https://network.pivotal.io/api/v2/products/product-4/product_files/3"
            }
          }
        }
      ],
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-4/file_groups/1"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-4/file_groups"
    }
  }
}

GET /api/v2/products/:product_slug/file_groups/:file_group_id

  • Show a file group for a product
    • returns 200 if the file group is found
    • returns 401 if the user could not be authenticated
    • returns 403 if the user is not permissioned to view the file group
    • returns 404 if the product or file group is not found
  • Authentication required

Example

Request


GET /api/v2/products/product-5/file_groups/2 HTTP/1.1
Accept: application/json
Authorization: Token token="validtoken"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 734
Content-Type: application/json; charset=utf-8
ETag: W/"c823245547713c75334a99d199e804c1"


{
  "id": 2,
  "name": "File Group 2",
  "product": {
    "id": 5,
    "name": "Product 5",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/product-5"
      },
      "releases": {
        "href": "https://network.pivotal.io/api/v2/products/product-5/releases"
      },
      "product_files": {
        "href": "https://network.pivotal.io/api/v2/products/product-5/product_files"
      },
      "file_groups": {
        "href": "https://network.pivotal.io/api/v2/products/product-5/file_groups"
      }
    }
  },
  "product_files": [
    {
      "id": 4,
      "aws_object_key": "product-5/product-file-4.txt",
      "file_version": "1.0.0",
      "name": "Product File 4",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-5/product_files/4"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-5/file_groups/2"
    }
  }
}

POST /api/v2/products/:product_slug/file_groups

  • Create a new file group for a product
    • returns 201 if a new file group is successfully created
    • returns 401 if the user could not be authenticated
    • returns 403 if the user is not permissioned to create file groups
    • returns 404 if the product or a product file is not found
    • returns 422 error creating the file group
  • Authentication required
  • The product_files key cannot be updated by this method. Please use /api/v2/products/:product.slug/file_groups/:file_group_id/add_product_file /api/v2/products/:product.slug/file_groups/:file_group_id/remove_product_file

Example

Request


POST /api/v2/products/product-6/file_groups HTTP/1.1
Accept: application/json
Authorization: Token token="validtoken"
Content-Length: 43
Content-Type: application/json
Host: network.pivotal.io


{
  "file_group": {
    "name": "my new file group"
  }
}

Response


HTTP/1.1 201
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 538
Content-Type: application/json; charset=utf-8
ETag: W/"e461075e47ca6dc68cdcecdb99e4dda3"


{
  "id": 3,
  "name": "my new file group",
  "product": {
    "id": 6,
    "name": "Product 6",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/product-6"
      },
      "releases": {
        "href": "https://network.pivotal.io/api/v2/products/product-6/releases"
      },
      "product_files": {
        "href": "https://network.pivotal.io/api/v2/products/product-6/product_files"
      },
      "file_groups": {
        "href": "https://network.pivotal.io/api/v2/products/product-6/file_groups"
      }
    }
  },
  "product_files": [

  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-6/file_groups/3"
    }
  }
}

PATCH /api/v2/products/:product_slug/file_groups/:file_group_id

  • Updates an existing file group for a product
    • returns 200 if the file group is successfully updated
    • returns 401 if the user could not be authenticated
    • returns 403 if the user is not permissioned to update file groups
    • returns 404 if the product or file group is not found
    • returns 422 error updating the file group
  • Authentication required
  • The product_files key cannot be updated by this method. Please use /api/v2/products/:product.slug/file_groups/:file_group_id/add_product_file /api/v2/products/:product.slug/file_groups/:file_group_id/remove_product_file

Example

Request


PATCH /api/v2/products/product-7/file_groups/5 HTTP/1.1
Accept: application/json
Authorization: Token token="validtoken"
Content-Length: 46
Content-Type: application/json
Host: network.pivotal.io


{
  "file_group": {
    "name": "new file group name!"
  }
}

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 742
Content-Type: application/json; charset=utf-8
ETag: W/"2d1e44b56dcf5a87c5792db780e0c5c5"


{
  "id": 5,
  "name": "new file group name!",
  "product": {
    "id": 7,
    "name": "Product 7",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/product-7"
      },
      "releases": {
        "href": "https://network.pivotal.io/api/v2/products/product-7/releases"
      },
      "product_files": {
        "href": "https://network.pivotal.io/api/v2/products/product-7/product_files"
      },
      "file_groups": {
        "href": "https://network.pivotal.io/api/v2/products/product-7/file_groups"
      }
    }
  },
  "product_files": [
    {
      "id": 6,
      "aws_object_key": "product-7/product-file-6.txt",
      "file_version": "1.0.0",
      "name": "Product File 6",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-7/product_files/6"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-7/file_groups/5"
    }
  }
}

PATCH /api/v2/products/:product_slug/file_groups/:file_group_id/add_product_file

  • Adds a product file to a file group
  • Required fields: product_file
    • returns 204 if the product file is successfully added to the file group
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to modify this file group
    • returns 404 if the product, file group, or product file cannot be found
    • returns 422 error adding the product file
  • Authorization: user api token

Example

Request


PATCH /api/v2/products/product-8/file_groups/6/add_product_file HTTP/1.1
Accept: application/json
Authorization: Token token="validtoken"
Content-Length: 25
Content-Type: application/json
Host: network.pivotal.io


{
  "product_file": {
    "id": 7
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

PATCH /api/v2/products/:product_slug/file_groups/:file_group_id/remove_product_file

  • Removes a product file from the specified file group
  • Required fields: product_file
    • returns 204 if the product file is removed
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to modify this file group
    • returns 404 if the product, file group, or product file cannot be found
  • Authorization: user api token

Example

Request


PATCH /api/v2/products/product-9/file_groups/7/remove_product_file HTTP/1.1
Accept: application/json
Authorization: Token token="validtoken"
Content-Length: 25
Content-Type: application/json
Host: network.pivotal.io


{
  "product_file": {
    "id": 8
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

DELETE /api/v2/products/:product_slug/file_groups/:file_group_id

  • Deletes a file group
    • returns 200 if the file group is deleted
    • returns 401 if the user could not be authenticated
    • returns 403 if the user is not permissioned to delete file groups
    • returns 404 if the product or file group is not found
  • Authentication required

Example

Request


DELETE /api/v2/products/product-10/file_groups/8 HTTP/1.1
Accept: application/json
Authorization: Token token="validtoken"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 743
Content-Type: application/json; charset=utf-8
ETag: W/"242b5a12978b40127c493e0e01bccf3f"


{
  "id": 8,
  "name": "File Group 7",
  "product": {
    "id": 10,
    "name": "Product 10",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/product-10"
      },
      "releases": {
        "href": "https://network.pivotal.io/api/v2/products/product-10/releases"
      },
      "product_files": {
        "href": "https://network.pivotal.io/api/v2/products/product-10/product_files"
      },
      "file_groups": {
        "href": "https://network.pivotal.io/api/v2/products/product-10/file_groups"
      }
    }
  },
  "product_files": [
    {
      "id": 9,
      "aws_object_key": "product-10/product-file-9.txt",
      "file_version": "1.0.0",
      "name": "Product File 9",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-10/product_files/9"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-10/file_groups/8"
    }
  }
}

GET /api/v2/products/:product_slug/releases

  • Lists releases associated with the specified product
    • returns 200 if the releases are found
    • returns 401 if user could not be authenticated
    • returns 404 if the product cannot be found
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/product-40/releases HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-33"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 4745
Content-Type: application/json; charset=utf-8
ETag: W/"60d4d0647388a6c34d412e918a7e5df5"


{
  "releases": [
    {
      "id": 60,
      "version": "1.2.1-alpha",
      "release_type": "Minor Release",
      "release_date": "2017-02-09",
      "release_notes_url": "http://example.com/release",
      "availability": "Admins Only",
      "description": "Release description",
      "eula": {
        "id": 46,
        "slug": "pivotal_software_eula",
        "name": "Pivotal Software EULA",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/eulas/46"
          }
        }
      },
      "end_of_support_date": "2015-05-10",
      "end_of_guidance_date": "2015-06-30",
      "end_of_availability_date": "2015-07-04",
      "eccn": "5D002",
      "license_exception": "ENC Unrestricted",
      "controlled": false,
      "updated_at": "2017-02-09T15:16:33.638Z",
      "software_files_updated_at": "2017-02-09T15:16:33.638Z",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/60"
        },
        "eula_acceptance": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/60/eula_acceptance"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/60/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/60/file_groups"
        },
        "user_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/60/user_groups"
        }
      }
    },
    {
      "id": 59,
      "version": "2.0.1-beta1",
      "release_type": "Major Release",
      "release_date": "2017-02-09",
      "release_notes_url": "http://example.com/release",
      "availability": "Selected User Groups Only",
      "description": "Release description",
      "eula": {
        "id": 46,
        "slug": "pivotal_software_eula",
        "name": "Pivotal Software EULA",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/eulas/46"
          }
        }
      },
      "end_of_support_date": "2015-05-10",
      "end_of_guidance_date": "2015-06-30",
      "end_of_availability_date": "2015-07-04",
      "eccn": "5D002",
      "license_exception": "ENC Unrestricted",
      "controlled": false,
      "updated_at": "2017-02-09T15:16:33.617Z",
      "software_files_updated_at": "2017-02-09T15:16:33.599Z",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/59"
        },
        "eula_acceptance": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/59/eula_acceptance"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/59/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/59/file_groups"
        },
        "user_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/59/user_groups"
        }
      }
    },
    {
      "id": 58,
      "version": "1.1.1",
      "release_type": "Minor Release",
      "release_date": "2017-02-09",
      "release_notes_url": "http://example.net/release-notes1",
      "availability": "Admins Only",
      "description": "Interesting release facts",
      "eula": {
        "id": 46,
        "slug": "pivotal_software_eula",
        "name": "Pivotal Software EULA",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/eulas/46"
          }
        }
      },
      "end_of_support_date": "2015-05-10",
      "end_of_guidance_date": "2015-06-30",
      "end_of_availability_date": "2015-07-04",
      "eccn": "5D002",
      "license_exception": "ENC Unrestricted",
      "controlled": false,
      "updated_at": "2017-02-09T15:16:33.482Z",
      "software_files_updated_at": "2017-02-09T15:16:33.482Z",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/58"
        },
        "eula_acceptance": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/58/eula_acceptance"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/58/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/58/file_groups"
        },
        "user_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/58/user_groups"
        }
      }
    },
    {
      "id": 57,
      "version": "1.0.1",
      "release_type": "Major Release",
      "release_date": "2017-02-09",
      "release_notes_url": "http://example.com/release",
      "availability": "Admins Only",
      "description": "Release description",
      "eula": {
        "id": 46,
        "slug": "pivotal_software_eula",
        "name": "Pivotal Software EULA",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/eulas/46"
          }
        }
      },
      "end_of_support_date": "2015-05-10",
      "end_of_guidance_date": "2015-06-30",
      "end_of_availability_date": "2015-07-04",
      "eccn": "5D002",
      "license_exception": "ENC Unrestricted",
      "controlled": false,
      "updated_at": "2017-02-09T15:16:33.453Z",
      "software_files_updated_at": "2017-02-09T15:16:33.453Z",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/57"
        },
        "eula_acceptance": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/57/eula_acceptance"
        },
        "product_files": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/57/product_files"
        },
        "file_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/57/file_groups"
        },
        "user_groups": {
          "href": "https://network.pivotal.io/api/v2/products/product-40/releases/57/user_groups"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-40/releases"
    }
  }
}

GET /api/v2/products/:product_slug/releases/:id

  • Returns a specific release associated with the specified product
    • returns 200 if the release is found
    • returns 401 if user could not be authenticated
    • returns 404 if the product or release cannot be found
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/product-41/releases/61 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-34"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 2080
Content-Type: application/json; charset=utf-8
ETag: W/"e829defc0ed41afdc63d7e9bb1199827"


{
  "id": 61,
  "version": "1.1.1",
  "release_type": "Major Release",
  "release_date": "2017-02-09",
  "release_notes_url": "http://example.com/release",
  "availability": "Admins Only",
  "description": "Release description",
  "eula": {
    "id": 47,
    "slug": "pivotal_software_eula",
    "name": "Pivotal Software EULA",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/eulas/47"
      }
    }
  },
  "end_of_support_date": "2015-05-10",
  "end_of_guidance_date": "2015-06-30",
  "end_of_availability_date": "2015-07-04",
  "eccn": "5D002",
  "license_exception": "ENC Unrestricted",
  "controlled": false,
  "product_files": [
    {
      "id": 42,
      "aws_object_key": "product-60/product-file-35.txt",
      "file_version": "1.0.0",
      "name": "Product File 35",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-41/releases/61/product_files/42"
        },
        "download": {
          "href": "https://network.pivotal.io/api/v2/products/product-41/releases/61/product_files/42/download"
        },
        "signature_file_download": {
          "href": null
        }
      }
    }
  ],
  "file_groups": [
    {
      "id": 13,
      "name": "File Group 10",
      "product_files": [
        {
          "id": 43,
          "aws_object_key": "product-60/product-file-36.txt",
          "file_version": "1.0.0",
          "name": "Product File 36",
          "_links": {
            "self": {
              "href": "https://network.pivotal.io/api/v2/products/product-41/releases/61/product_files/43"
            },
            "download": {
              "href": "https://network.pivotal.io/api/v2/products/product-41/releases/61/product_files/43/download"
            },
            "signature_file_download": {
              "href": null
            }
          }
        }
      ],
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-41/file_groups/13"
        }
      }
    }
  ],
  "updated_at": "2017-02-09T15:16:34.210Z",
  "software_files_updated_at": "2017-02-09T15:16:34.209Z",
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-41/releases/61"
    },
    "eula_acceptance": {
      "href": "https://network.pivotal.io/api/v2/products/product-41/releases/61/eula_acceptance"
    },
    "product_files": {
      "href": "https://network.pivotal.io/api/v2/products/product-41/releases/61/product_files"
    },
    "file_groups": {
      "href": "https://network.pivotal.io/api/v2/products/product-41/releases/61/file_groups"
    },
    "user_groups": {
      "href": "https://network.pivotal.io/api/v2/products/product-41/releases/61/user_groups"
    }
  }
}

GET /api/v2/products/:product_slug/releases/latest

  • Returns the latest release associated with the specified product
    • returns 200 if the release is found
    • returns 401 if user could not be authenticated
    • returns 404 if the product cannot be found or has no semver-compliant releases
  • Authentication optional, but required to view releases not available to public
  • Major and minor query strings are optional (must provide major when querying with minor)
  • Only releases with semver-compliant versions will be found

Example

Request


GET /api/v2/products/product-42/releases/latest?major=1&minor=1 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-35"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 935
Content-Type: application/json; charset=utf-8
ETag: W/"35d0fd5b273ee81806b72d1d2c82941e"


{
  "id": 63,
  "version": "1.1.2",
  "release_type": "Major Release",
  "release_date": "2017-02-09",
  "availability": "Admins Only",
  "eula": {
    "id": 48,
    "slug": "pivotal_software_eula",
    "name": "Pivotal Software EULA",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/eulas/48"
      }
    }
  },
  "controlled": false,
  "product_files": [

  ],
  "file_groups": [

  ],
  "updated_at": "2017-02-09T15:16:34.576Z",
  "software_files_updated_at": "2017-02-09T15:16:34.576Z",
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-42/releases/63"
    },
    "eula_acceptance": {
      "href": "https://network.pivotal.io/api/v2/products/product-42/releases/63/eula_acceptance"
    },
    "product_files": {
      "href": "https://network.pivotal.io/api/v2/products/product-42/releases/63/product_files"
    },
    "file_groups": {
      "href": "https://network.pivotal.io/api/v2/products/product-42/releases/63/file_groups"
    },
    "user_groups": {
      "href": "https://network.pivotal.io/api/v2/products/product-42/releases/63/user_groups"
    }
  }
}

POST /api/v2/products/:product_slug/releases

  • Create a release associated with the specified product
    • returns 201 if the release is created
    • returns 400 if there is no release key in the request payload
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to create releases on the product
    • returns 404 if the product or EULA cannot be found
    • returns 422 if the release cannot be created due to invalid release data
  • Authentication required
  • Valid release types: All-In-One, Major Release, Minor Release, Service Release, Maintenance Release, Security Release, Alpha Release, Beta Release, Edge Release
  • Only Admins Only can be set for the availability
  • The product_files, file_groups, and user_groups keys cannot be updated by this method. After creating the release, please use:
    • /api/v2/products/:product_slug/releases/:release_id/add_product_file
    • /api/v2/products/:product_slug/releases/:release_id/add_file_group
    • /api/v2/products/:product_slug/releases/:release_id/add_user_group
  • Product Admins must certify that all OSS and third-party software used in this release has been cleared by the legal team by entering a value of confirm for the oss_compliant field
  • Contact product_ops@pivotal.io for more information about the Export Control Classification Number (ECCN), License Exception, and Controlled status

Example

Request


POST /api/v2/products/product-43/releases HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-36"
Content-Length: 453
Content-Type: application/json
Host: network.pivotal.io


{
  "release": {
    "version": "1.0.12",
    "release_notes_url": "http://example.com/release",
    "description": "Release description",
    "release_date": "2013-12-11",
    "release_type": "Security Release",
    "availability": "Admins Only",
    "eula": {
      "slug": "pivotal_software_eula"
    },
    "oss_compliant": "confirm",
    "end_of_support_date": "2015-5-10",
    "end_of_guidance_date": "2015-6-30",
    "end_of_availability_date": "2015-7-4",
    "eccn": "5D002",
    "license_exception": "ENC Unrestricted",
    "controlled": true
  }
}

Response


HTTP/1.1 201
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 1284
Content-Type: application/json; charset=utf-8
ETag: W/"e66b7f448128132aa104f33ea25bfad8"
Location: https://network.pivotal.io/api/v2/products/product-43/releases/65


{
  "status": 201,
  "message": "successfully created release '65' for product 'product-43'",
  "release": {
    "id": 65,
    "version": "1.0.12",
    "release_type": "Security Release",
    "release_date": "2013-12-11",
    "release_notes_url": "http://example.com/release",
    "availability": "Admins Only",
    "description": "Release description",
    "eula": {
      "id": 49,
      "slug": "pivotal_software_eula",
      "name": "Pivotal Software EULA",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/eulas/49"
        }
      }
    },
    "end_of_support_date": "2015-05-10",
    "end_of_guidance_date": "2015-06-30",
    "end_of_availability_date": "2015-07-04",
    "eccn": "5D002",
    "license_exception": "ENC Unrestricted",
    "controlled": true,
    "product_files": [

    ],
    "file_groups": [

    ],
    "updated_at": "2017-02-09T15:16:35.196Z",
    "software_files_updated_at": "2017-02-09T15:16:35.196Z",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/product-43/releases/65"
      },
      "eula_acceptance": {
        "href": "https://network.pivotal.io/api/v2/products/product-43/releases/65/eula_acceptance"
      },
      "product_files": {
        "href": "https://network.pivotal.io/api/v2/products/product-43/releases/65/product_files"
      },
      "file_groups": {
        "href": "https://network.pivotal.io/api/v2/products/product-43/releases/65/file_groups"
      },
      "user_groups": {
        "href": "https://network.pivotal.io/api/v2/products/product-43/releases/65/user_groups"
      }
    }
  }
}

PATCH /api/v2/products/:product_slug/releases/:id

  • Update an existing release associated with the specified product
    • returns 200 if the release is updated
    • returns 400 if there is no release key in the request payload
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to update releases on the product
    • returns 404 if the product cannot be found
    • returns 422 if the release cannot be updated due to invalid release data
  • Authentication required
  • Valid release types: All-In-One, Major Release, Minor Release, Service Release, Maintenance Release, Security Release, Alpha Release, Beta Release, Edge Release
  • Pivotal Product Admins can set the availability to any of the following: Admins Only, Selected User Groups Only, All Users
  • The product_files, file_groups, and user_groups keys cannot be updated by this method. Please use:
    • /api/v2/products/:product_slug/releases/:release_id/add_product_file
    • /api/v2/products/:product_slug/releases/:release_id/remove_product_file
    • /api/v2/products/:product_slug/releases/:release_id/add_file_group
    • /api/v2/products/:product_slug/releases/:release_id/remove_file_group
    • /api/v2/products/:product_slug/releases/:release_id/add_user_group
    • /api/v2/products/:product_slug/releases/:release_id/remove_user_group
  • Product Admins must certify that all OSS and third-party software used in this release has been cleared by the legal team by entering a value of confirm for the oss_compliant field
  • Releases cannot be made available to All Users or Selected User Groups Only if any associated product files have the in_progress or failed_to_transfer file transfer status values.
  • Releases cannot be made available to All Users or Selected User Groups Only if any associated file groups contain product files that have the in_progress or failed_to_transfer file transfer status values.
  • Contact product_ops@pivotal.io for more information about the Export Control Classification Number (ECCN), License Exception, and Controlled status

Example

Request


PATCH /api/v2/products/product-44/releases/66 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-37"
Content-Length: 276
Content-Type: application/json
Host: network.pivotal.io


{
  "release": {
    "version": "9.9.9",
    "availability": "All Users",
    "release_type": "Major Release",
    "end_of_support_date": "2015-5-10",
    "end_of_guidance_date": "2015-6-30",
    "end_of_availability_date": "2015-7-4",
    "oss_compliant": "confirm",
    "eccn": "5D002",
    "license_exception": "ENC Unrestricted"
  }
}

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 2089
Content-Type: application/json; charset=utf-8
ETag: W/"1add77234dcf47f617aa61bccdf0e923"
Location: https://network.pivotal.io/api/v2/products/product-44/releases/66


{
  "status": 200,
  "message": "successfully updated release '66' for product 'product-44'",
  "release": {
    "id": 66,
    "version": "9.9.9",
    "release_type": "Major Release",
    "release_date": "2017-02-09",
    "availability": "All Users",
    "eula": {
      "id": 51,
      "slug": "pivotal_software_eula",
      "name": "Pivotal Software EULA",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/eulas/51"
        }
      }
    },
    "end_of_support_date": "2015-05-10",
    "end_of_guidance_date": "2015-06-30",
    "end_of_availability_date": "2015-07-04",
    "eccn": "5D002",
    "license_exception": "ENC Unrestricted",
    "controlled": false,
    "product_files": [
      {
        "id": 45,
        "aws_object_key": "product-63/product-file-38.txt",
        "file_version": "1.0.0",
        "name": "Product File 38",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/products/product-44/releases/66/product_files/45"
          },
          "download": {
            "href": "https://network.pivotal.io/api/v2/products/product-44/releases/66/product_files/45/download"
          },
          "signature_file_download": {
            "href": null
          }
        }
      }
    ],
    "file_groups": [
      {
        "id": 14,
        "name": "File Group 11",
        "product_files": [
          {
            "id": 45,
            "aws_object_key": "product-63/product-file-38.txt",
            "file_version": "1.0.0",
            "name": "Product File 38",
            "_links": {
              "self": {
                "href": "https://network.pivotal.io/api/v2/products/product-44/releases/66/product_files/45"
              },
              "download": {
                "href": "https://network.pivotal.io/api/v2/products/product-44/releases/66/product_files/45/download"
              },
              "signature_file_download": {
                "href": null
              }
            }
          }
        ],
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/products/product-44/file_groups/14"
          }
        }
      }
    ],
    "updated_at": "2017-02-09T15:16:35.775Z",
    "software_files_updated_at": "2017-02-09T15:16:35.631Z",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/product-44/releases/66"
      },
      "eula_acceptance": {
        "href": "https://network.pivotal.io/api/v2/products/product-44/releases/66/eula_acceptance"
      },
      "product_files": {
        "href": "https://network.pivotal.io/api/v2/products/product-44/releases/66/product_files"
      },
      "file_groups": {
        "href": "https://network.pivotal.io/api/v2/products/product-44/releases/66/file_groups"
      },
      "user_groups": {
        "href": "https://network.pivotal.io/api/v2/products/product-44/releases/66/user_groups"
      }
    }
  }
}

DELETE /api/v2/products/:product_slug/releases/:id

  • Delete a release from a product.
    • returns 204 if the release has been deleted
    • returns 401 if user could not be authenticated
    • returns 403 if user is not permitted to delete releases from the product
    • returns 404 if the product or release cannot be found
  • Authentication required
  • NOTE: This will not remove files or file groups from the product. This action cannot be undone.

Example

Request


DELETE /api/v2/products/product-45/releases/67 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-38"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 204
Cache-Control: no-cache

GET /api/v2/releases/release_types

  • Returns the list of Release Types
  • No authentication required

Example

Request


GET /api/v2/releases/release_types HTTP/1.1
Accept: application/json
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 268
Content-Type: application/json; charset=utf-8
ETag: W/"b3f43b0e3bfefdfca791d4e9507e7596"
Location: https://network.pivotal.io/api/v2/releases/release_types


{
  "status": 200,
  "release_types": [
    "All-In-One",
    "Major Release",
    "Minor Release",
    "Service Release",
    "Maintenance Release",
    "Security Release",
    "Alpha Release",
    "Beta Release",
    "Edge Release"
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/releases/release_types"
    }
  }
}

GET /api/v2/products/:product_slug/releases/:release_id/product_files

  • List product files associated with the specified release
    • returns 200 if the release is found
    • returns 401 if user could not be authenticated
    • returns 404 if the product or release cannot be found
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/product-30/releases/39/product_files HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-20"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 876
Content-Type: application/json; charset=utf-8
ETag: W/"44659888946b1b423835e5a31e1ebe28"


{
  "product_files": [
    {
      "id": 32,
      "aws_object_key": "product-45/product-file-25.txt",
      "file_version": "1.0.0",
      "name": "Product File 25",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-30/releases/39/product_files/32"
        },
        "download": {
          "href": "https://network.pivotal.io/api/v2/products/product-30/releases/39/product_files/32/download"
        },
        "signature_file_download": {
          "href": null
        }
      }
    },
    {
      "id": 31,
      "aws_object_key": "product-45/product-file-24.txt",
      "file_version": "1.0.0",
      "name": "Product File 24",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-30/releases/39/product_files/31"
        },
        "download": {
          "href": "https://network.pivotal.io/api/v2/products/product-30/releases/39/product_files/31/download"
        },
        "signature_file_download": {
          "href": null
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-30/releases/39/product_files"
    }
  }
}

GET /api/v2/products/:product_slug/releases/:release_id/product_files/:id

  • Show a product file for a product's release
    • returns 200 if the product file is found
    • returns 401 if the user could not be authenticated
    • returns 403 if the user is not permissioned to view the product file
    • returns 404 if the product, release, or the product file cannot be found
  • Authentication required

Example

Request


GET /api/v2/products/product-31/releases/40/product_files/33 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-21"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 690
Content-Type: application/json; charset=utf-8
ETag: W/"bae560adbe415c0857c6a335c4651679"


{
  "product_file": {
    "id": 33,
    "aws_object_key": "product-46/product-file-26.txt",
    "description": "product description 31",
    "docs_url": null,
    "file_transfer_status": "complete",
    "file_type": "Software",
    "file_version": "1.0.0",
    "has_signature_file": true,
    "included_files": [

    ],
    "md5": "c705c6e6339ebb3417ed1f118efbe620",
    "name": "Product File 26",
    "platforms": [

    ],
    "ready_to_serve": true,
    "released_at": "2017-02-09",
    "size": 1024,
    "system_requirements": [

    ],
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/product-31/releases/40/product_files/33"
      },
      "download": {
        "href": "https://network.pivotal.io/api/v2/products/product-31/releases/40/product_files/33/download"
      },
      "signature_file_download": {
        "href": null
      }
    }
  }
}

PATCH /api/v2/products/:product_slug/releases/:release_id/add_product_file

  • Associates a product file with the specified release
  • Required fields: product_file
    • returns 204 if the product file is successfully associated
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to modify this release
    • returns 404 if the product, release, or product file cannot be found
    • returns 422 error associating the product file
  • Authorization: user api token

Example

Request


PATCH /api/v2/products/product-32/releases/41/add_product_file HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-22"
Content-Length: 26
Content-Type: application/json
Host: network.pivotal.io


{
  "product_file": {
    "id": 34
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

PATCH /api/v2/products/:product_slug/releases/:release_id/remove_product_file

  • Removes a product file from the specified release
  • Required fields: product_file
    • returns 204 if the product file is removed
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to modify this release
    • returns 404 if the product, release, or product file cannot be found
  • Authorization: user api token

Example

Request


PATCH /api/v2/products/product-33/releases/42/remove_product_file HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-23"
Content-Length: 26
Content-Type: application/json
Host: network.pivotal.io


{
  "product_file": {
    "id": 35
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

GET /api/v2/products/:product_slug/releases/:release_id/file_groups

  • List file groups on a release
    • returns 200 on success
    • returns 401 if the user could not be authenticated
    • returns 404 if the product or release cannot be found or the user is not permitted to view
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/product-27/releases/36/file_groups HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-17"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 1582
Content-Type: application/json; charset=utf-8
ETag: W/"db2a279e443e18329a2088246c12c125"


{
  "file_groups": [
    {
      "id": 9,
      "name": "Alpha Users",
      "product_files": [
        {
          "id": 26,
          "aws_object_key": "product-42/special-product-alpha.txt",
          "file_version": "1.0.0",
          "name": "Special Product Alpha",
          "_links": {
            "self": {
              "href": "https://network.pivotal.io/api/v2/products/product-27/releases/36/product_files/26"
            },
            "download": {
              "href": "https://network.pivotal.io/api/v2/products/product-27/releases/36/product_files/26/download"
            },
            "signature_file_download": {
              "href": null
            }
          }
        }
      ],
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-27/file_groups/9"
        }
      }
    },
    {
      "id": 10,
      "name": "Alpha Users",
      "product_files": [
        {
          "id": 28,
          "aws_object_key": "product-42/special-product-alpha-2.txt",
          "file_version": "1.0.0",
          "name": "Special Product Alpha 2",
          "_links": {
            "self": {
              "href": "https://network.pivotal.io/api/v2/products/product-27/releases/36/product_files/28"
            },
            "download": {
              "href": "https://network.pivotal.io/api/v2/products/product-27/releases/36/product_files/28/download"
            },
            "signature_file_download": {
              "href": null
            }
          }
        },
        {
          "id": 27,
          "aws_object_key": "product-42/special-product-alpha-1.txt",
          "file_version": "1.0.0",
          "name": "Special Product Alpha 1",
          "_links": {
            "self": {
              "href": "https://network.pivotal.io/api/v2/products/product-27/releases/36/product_files/27"
            },
            "download": {
              "href": "https://network.pivotal.io/api/v2/products/product-27/releases/36/product_files/27/download"
            },
            "signature_file_download": {
              "href": null
            }
          }
        }
      ],
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/product-27/file_groups/10"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-27/releases/36/file_groups"
    }
  }
}

PATCH /api/v2/products/:product_slug/releases/:release_id/add_file_group

  • Associates an existing file group to the specified release
  • Required fields: file_group
    • returns 204 if the file group is successfully associated
    • returns 400 if the request payload is malformed
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to attach file groups to the release
    • returns 404 if the product, release, or file group cannot be found
    • returns 422 if the file group could not be added to the release
  • Authorization: user api token

Example

Request


PATCH /api/v2/products/product-28/releases/37/add_file_group HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-18"
Content-Length: 24
Content-Type: application/json
Host: network.pivotal.io


{
  "file_group": {
    "id": 11
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

PATCH /api/v2/products/:product_slug/releases/:release_id/remove_file_group

  • Removes a file group from the specified release
  • Required fields: file_group
    • returns 204 if the file group is successfully removed from the release
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to modify this release
    • returns 404 if the product, release, or file group cannot be found
  • Authorization: user api token

Example

Request


PATCH /api/v2/products/product-29/releases/38/remove_file_group HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-19"
Content-Length: 24
Content-Type: application/json
Host: network.pivotal.io


{
  "file_group": {
    "id": 12
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

GET /api/v2/products/:product_slug/releases/:release_id/user_groups

  • Get user groups associated with the specified release
    • returns 200 if user groups are returned successfully
    • returns 401 if user could not be authenticated
    • returns 403 if user does not have access to manage the product
    • returns 404 if the product or release cannot be found
  • Authentication required

Example

Request


GET /api/v2/products/product-37/releases/54/user_groups HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-30"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 270
Content-Type: application/json; charset=utf-8
ETag: W/"2a073fbdee05cf94fcaf31377bbd061e"


{
  "user_groups": [
    {
      "id": 1,
      "name": "Group Name #1",
      "description": "Group Description #1",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/user_groups/1"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-37/releases/54/user_groups"
    }
  }
}

PATCH /api/v2/products/:product_slug/releases/:release_id/add_user_group

  • Grants the user group access to the release
    • returns 204 if the user group is successfully granted access to the release
    • returns 400 if there is no user_group key in the request payload
    • returns 403 if user does not have access to update the release
    • returns 404 if the release or user group cannot be found
    • returns 422 if the user group is already associated with the release
  • Authentication required
  • The user group will only be able to use this access if the release type is Selected User Groups Only

Example

Request


PATCH /api/v2/products/product-38/releases/55/add_user_group HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-31"
Content-Length: 23
Content-Type: application/json
Host: network.pivotal.io


{
  "user_group": {
    "id": 2
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

PATCH /api/v2/products/:product_slug/releases/:release_id/remove_user_group

  • Revokes the user group's access to the release
    • returns 204 if the user group's access to the release is successfully revoked
    • returns 400 if there is no user_group key in the request payload
    • returns 403 if user does not have access to update the release
    • returns 404 if the release or user group cannot be found
  • Authentication required
  • Removing a user group will only affect that group's visibility of the release if the release type is Selected User Groups Only

Example

Request


PATCH /api/v2/products/product-39/releases/56/remove_user_group HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-32"
Content-Length: 23
Content-Type: application/json
Host: network.pivotal.io


{
  "user_group": {
    "id": 3
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

GET /api/v2/products/:product_slug/releases/:release_id/dependencies

  • List dependencies associated with the specified release
    • returns 200 on success
    • returns 401 if the user could not be authenticated
    • returns 404 if the product or release cannot be found
  • Also includes dependencies that match any of the release's dependency specifiers
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/product-19/releases/23/dependencies HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-9"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 845
Content-Type: application/json; charset=utf-8
ETag: W/"46ceb782168742f9307940c5802e283d"


{
  "dependencies": [
    {
      "release": {
        "id": 22,
        "version": "1.0.19-alpha",
        "product": {
          "id": 28,
          "name": "Product 28"
        },
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/products/product-21/releases/22"
          }
        }
      }
    },
    {
      "release": {
        "id": 21,
        "version": "1.0.18-alpha",
        "product": {
          "id": 27,
          "name": "Product 27"
        },
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/products/product-20/releases/21"
          }
        }
      }
    },
    {
      "release": {
        "id": 24,
        "version": "1.3.1-test",
        "product": {
          "id": 25,
          "name": "Product 25"
        },
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/products/product-18/releases/24"
          }
        }
      }
    },
    {
      "release": {
        "id": 26,
        "version": "1.4.7",
        "product": {
          "id": 25,
          "name": "Product 25"
        },
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/products/product-18/releases/26"
          }
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-19/releases/23/dependencies"
    }
  }
}

PATCH /api/v2/products/:product_slug/releases/:release_id/add_dependency

  • Associates a release dependency with the specified release
    • returns 204 if the dependency is successfully associated with the release
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if the user could not be authenticated
    • returns 403 if user does not have access to modify this release
    • returns 404 if the product, release or release dependency cannot be found
  • Authentication required

Example

Request


PATCH /api/v2/products/product-22/releases/27/add_dependency HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-10"
Content-Length: 32
Content-Type: application/json
Host: network.pivotal.io


{
  "dependency": {
    "release_id": 28
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

PATCH /api/v2/products/:product_slug/releases/:release_id/remove_dependency

  • Removes a release dependency from the specified release
    • returns 204 if the dependency is successfully removed from the release
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if the user could not be authenticated
    • returns 403 if user does not have access to modify this release
    • returns 404 if the product, release or release dependency cannot be found
  • Authentication required

Example

Request


PATCH /api/v2/products/product-24/releases/29/remove_dependency HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-11"
Content-Length: 32
Content-Type: application/json
Host: network.pivotal.io


{
  "dependency": {
    "release_id": 30
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

POST /api/v2/products/:product_slug/releases/:release_id/dependency_specifiers

  • Creates a release dependency specifier. Dependency specifiers are rules for defining acceptable product versions for a given product dependency.
    • returns 201 on success
    • returns 401 if the user could not be authenticated
    • returns 403 if the user does not have permission to edit product
    • returns 404 if the product or release cannot be found
    • returns 422 if the dependency specifier is invalid
  • All public, semver-compliant releases for the chosen product that match the specifier will be included in the response from the dependencies API endpoint
  • Releases associated as dependencies by a dependency specifier cannot be selectively dissociated; delete the dependency specifier and use the add_dependency endpoint.
  • Versions of the product created in the future will be compared against the specifier
  • Supported specifiers:
    • Minor version:
      • MAJOR.MINOR.* for products other than 'Stemcells for PCF'
      • NUMBER.* for the 'Stemcells for PCF' product
      • Matches public, semver releases that have the given major and minor (or first number, if Stemcells)

Example

Request


POST /api/v2/products/release-product-slug/releases/31/dependency_specifiers HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-12"
Content-Length: 87
Content-Type: application/json
Host: network.pivotal.io


{
  "dependency_specifier": {
    "product_slug": "dependency-product-slug",
    "specifier": "1.2.*"
  }
}

Response


HTTP/1.1 201
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 255
Content-Type: application/json; charset=utf-8
ETag: W/"36399e27122fd5869e4e1265d27ce25a"


{
  "dependency_specifier": {
    "id": 3,
    "product": {
      "id": 33,
      "slug": "dependency-product-slug",
      "name": "Product 33"
    },
    "specifier": "1.2.*",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/release-product-slug/releases/31/dependency_specifiers/3"
      }
    }
  }
}

GET /api/v2/products/:product_slug/releases/:release_id/dependency_specifiers

  • Returns the release dependency specifiers for a release
    • returns 200 on success
    • returns 404 if the product or release cannot be found
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/release-product-slug/releases/32/dependency_specifiers HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-13"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 385
Content-Type: application/json; charset=utf-8
ETag: W/"f15962153e8ed5cc2d65a1372a1938b5"


{
  "dependency_specifiers": [
    {
      "id": 4,
      "product": {
        "id": 35,
        "slug": "dependency-product-slug",
        "name": "Product 35"
      },
      "specifier": "1.2.*",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/release-product-slug/releases/32/dependency_specifiers/4"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/release-product-slug/releases/32/dependency_specifiers"
    }
  }
}

GET /api/v2/products/:product_slug/releases/:release_id/dependency_specifiers/:id

  • Returns the release dependency specifier
    • returns 200 on success
    • returns 404 if the dependency specifier cannot be found
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/release-product-slug/releases/33/dependency_specifiers/5 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-14"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 255
Content-Type: application/json; charset=utf-8
ETag: W/"b4ea6331b28b096b85ce76588c372350"


{
  "dependency_specifier": {
    "id": 5,
    "product": {
      "id": 37,
      "slug": "dependency-product-slug",
      "name": "Product 37"
    },
    "specifier": "1.2.*",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/release-product-slug/releases/33/dependency_specifiers/5"
      }
    }
  }
}

DELETE /api/v2/products/:product_slug/releases/:release_id/dependency_specifiers/:id

  • Deletes a release dependency specifier
    • returns 204 on success
    • returns 401 if the user could not be authenticated
    • returns 403 if the user does not have permission to edit the product
    • returns 404 if the dependency specifier cannot be found

Example

Request


DELETE /api/v2/products/release-product-slug/releases/34/dependency_specifiers/6 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-15"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 204
Cache-Control: no-cache

GET /api/v2/products/:product_slug/releases/:release_id/upgrade_paths

  • List upgrade paths associated with the specified release
    • returns 200 on success
    • returns 401 if the user could not be authenticated
    • returns 404 if the product or release cannot be found
  • Also includes upgrade paths that match any of the release's upgrade path specifiers
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/product-34/releases/49/upgrade_paths HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-26"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 412
Content-Type: application/json; charset=utf-8
ETag: W/"afe17612bd23db29c93a8db95d8377e1"


{
  "upgrade_paths": [
    {
      "release": {
        "id": 48,
        "version": "1.0.42-alpha",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/products/product-34/releases/48"
          }
        }
      }
    },
    {
      "release": {
        "id": 47,
        "version": "1.0.41-alpha",
        "_links": {
          "self": {
            "href": "https://network.pivotal.io/api/v2/products/product-34/releases/47"
          }
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/product-34/releases/49/upgrade_paths"
    }
  }
}

PATCH /api/v2/products/:product_slug/releases/:release_id/add_upgrade_path

  • Associates a possible upgrade path to the specified release
    • returns 204 if the upgrade path is successfully associated with the release
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if the user could not be authenticated
    • returns 403 if user does not have access to modify this release
    • returns 404 if the product, release or upgrade path cannot be found
  • Authentication required

Example

Request


PATCH /api/v2/products/product-35/releases/50/add_upgrade_path HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-27"
Content-Length: 34
Content-Type: application/json
Host: network.pivotal.io


{
  "upgrade_path": {
    "release_id": 51
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

PATCH /api/v2/products/:product_slug/releases/:release_id/remove_upgrade_path

  • Removes an upgrade path from the specified release
    • returns 204 if the upgrade path is successfully removed from the release
    • returns 400 if there is a missing required field in the request payload
    • returns 401 if the user could not be authenticated
    • returns 403 if user does not have access to modify this release
    • returns 404 if the product, release or upgrade path cannot be found
  • Authentication required

Example

Request


PATCH /api/v2/products/product-36/releases/52/remove_upgrade_path HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-28"
Content-Length: 34
Content-Type: application/json
Host: network.pivotal.io


{
  "upgrade_path": {
    "release_id": 53
  }
}

Response


HTTP/1.1 204
Cache-Control: no-cache

POST /api/v2/products/:product_slug/releases/:release_id/upgrade_path_specifiers

  • Creates a release upgrade path specifier. Upgrade path specifiers are rules for defining acceptable versions from which to upgrade to the current release.
    • returns 201 on success
    • returns 401 if the user could not be authenticated
    • returns 403 if the user does not have permission to edit product
    • returns 404 if the product or release cannot be found
    • returns 422 if the dependency specifier is invalid
  • All public, semver-compliant releases within the product that match the specifier will be included in the response from the upgrade_paths API endpoint
  • Releases associated as upgrade paths by an upgrade path specifier cannot be selectively dissociated; delete the upgrade path specifier and use the add_upgrade_path endpoint instead.
  • Versions of the product created in the future will be included if they match the specifier
  • Supported specifiers:
    • Minor version:
      • MAJOR.MINOR.*
      • Matches public, semver releases that have the given major and minor

Example

Request


POST /api/v2/products/release-product-slug/releases/43/upgrade_path_specifiers HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-24"
Content-Length: 48
Content-Type: application/json
Host: network.pivotal.io


{
  "upgrade_path_specifier": {
    "specifier": "1.2.*"
  }
}

Response


HTTP/1.1 201
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 186
Content-Type: application/json; charset=utf-8
ETag: W/"3dde619eba85dd17a85f3eec346437b0"


{
  "upgrade_path_specifier": {
    "id": 1,
    "specifier": "1.2.*",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/release-product-slug/releases/43/upgrade_path_specifiers/1"
      }
    }
  }
}

DELETE /api/v2/products/:product_slug/releases/:release_id/upgrade_path_specifiers/:id

  • Deletes a release upgrade path specifier
    • returns 204 on success
    • returns 401 if the user could not be authenticated
    • returns 403 if the user does not have permission to edit the product
    • returns 404 if the upgrade path specifier cannot be found

Example

Request


DELETE /api/v2/products/release-product-slug/releases/44/upgrade_path_specifiers/2 HTTP/1.1
Accept: application/json
Authorization: Token token="api-token-25"
Content-Length: 0
Content-Type: application/json
Host: network.pivotal.io

Response


HTTP/1.1 204
Cache-Control: no-cache

GET /api/v2/products/:slug/releases/:release_id/upgrade_path_specifiers/:id

  • Returns the release upgrade path specifier
    • returns 200 on success
    • returns 404 if the upgrade path specifier cannot be found
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/release-product-slug/releases/45/upgrade_path_specifiers/3 HTTP/1.1
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Length: 0
Host: www.example.com

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 186
Content-Type: application/json; charset=utf-8
ETag: W/"4706fc47437d0d20cb62dad0d02b4147"


{
  "upgrade_path_specifier": {
    "id": 3,
    "specifier": "2.3.*",
    "_links": {
      "self": {
        "href": "https://network.pivotal.io/api/v2/products/release-product-slug/releases/45/upgrade_path_specifiers/3"
      }
    }
  }
}

GET /api/v2/products/:slug/releases/:release_id/upgrade_path_specifiers

  • Returns the upgrade path specifiers for the release
    • returns 200 on success
  • Authentication optional, but required to view releases not available to public

Example

Request


GET /api/v2/products/release-product-slug/releases/46/upgrade_path_specifiers HTTP/1.1
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Length: 0
Host: www.example.com

Response


HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 318
Content-Type: application/json; charset=utf-8
ETag: W/"69434959cb9eb71ebb0510a89ed92e36"


{
  "upgrade_path_specifiers": [
    {
      "id": 4,
      "specifier": "2.3.*",
      "_links": {
        "self": {
          "href": "https://network.pivotal.io/api/v2/products/release-product-slug/releases/46/upgrade_path_specifiers/4"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://network.pivotal.io/api/v2/products/release-product-slug/releases/46/upgrade_path_specifiers"
    }
  }
}